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:
144 edited

Legend:

Unmodified
Added
Removed

  • code/trunk

  • code/trunk/src/libraries/CMakeLists.txt

    r5929 r7401  
    1818 #
    1919
    20 INCLUDE_DIRECTORIES(
    21   ${CMAKE_SOURCE_DIR}/src/external
    22   ${CMAKE_CURRENT_SOURCE_DIR}
    23 )
     20INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})
    2421
    2522################ Sub Directories ################

  • 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)

  • code/trunk/src/libraries/network/ClientInformation.cc

    r6417 r7401  
    230230  * This function should only be applied to the head of the list
    231231  * @param clientID id to look for
     232  * @param look_backwards FIXME - add doc? parameter unused?
    232233  * @return pointer to the last element in the list or 0 if the search was unsuccessfull
    233234  */
    … …  
    244245  * This function goes forward through the list and looks for an element with clientID
    245246  * This function should only be applied to the head of the list
    246   * @param peer peer to look for
     247  * @param address peer to look for
     248  * @param look_backwards FIXME - add doc? parameter unused?
    247249  * @return pointer to the element in the list
    248250  */

  • code/trunk/src/libraries/network/GamestateClient.cc

    r7163 r7401  
    105105  * @return iterator pointing to the next object in the list
    106106  */
    107   void GamestateClient::removeObject(ObjectList<Synchronisable>::iterator &it) {
    108     ObjectList<Synchronisable>::iterator temp=it;
     107  void GamestateClient::removeObject(ObjectListIterator<Synchronisable> &it) {
     108    ObjectListIterator<Synchronisable> temp=it;
    109109    ++it;
    110110    temp->destroy(); // or delete?

  • code/trunk/src/libraries/network/synchronisable/Synchronisable.cc

    r7183 r7401  
    217217   * length of varx: size saved int syncvarlist
    218218   * @param mem pointer to allocated memory with enough size
     219   * @param sizes FIXME - add doc!
    219220   * @param id gamestateid of the gamestate to be saved (important for priorities)
    220221   * @param mode defines the direction in which the data will be send/received
    … …  
    288289   * @param mem pointer to the bytestream
    289290   * @param mode same as in getData
     291   * @param forceCallback FIXME - add doc!
    290292   * @return true/false
    291293   */
    … …  
    364366   * This function determines, wheter the object should be saved to the bytestream (according to its syncmode/direction)
    365367   * @param id gamestate id
     368   * @param mode FIXME - add doc!
    366369   * @return true/false
    367370   */

  • code/trunk/src/libraries/tools/ResourceCollection.cc

    r5781 r7401  
    5252    }
    5353
    54     void ResourceCollection::XMLPort(Element& xmlElement, XMLPort::Mode mode)
     54    void ResourceCollection::XMLPort(Element& xmlelement, XMLPort::Mode mode)
    5555    {
    56         XMLPortParam(ResourceCollection, "resourceGroup", setResourceGroup, getResourceGroup, xmlElement, mode);
    57         XMLPortObject(ResourceCollection, ResourceLocation, "", addResourceLocation, getResourceLocation, xmlElement, mode);
     56        XMLPortParam(ResourceCollection, "resourceGroup", setResourceGroup, getResourceGroup, xmlelement, mode);
     57        XMLPortObject(ResourceCollection, ResourceLocation, "", addResourceLocation, getResourceLocation, xmlelement, mode);
    5858    }
    5959

  • code/trunk/src/libraries/tools/ResourceCollection.h

    r6105 r7401  
    4444        virtual ~ResourceCollection();
    4545
    46         virtual void XMLPort(Element& xmlElement, XMLPort::Mode mode);
     46        virtual void XMLPort(Element& xmlelement, XMLPort::Mode mode);
    4747
    4848        void setResourceGroup(const std::string& resourceGroup);

  • code/trunk/src/libraries/tools/ResourceLocation.cc

    r7174 r7401  
    5656    }
    5757
    58     void ResourceLocation::XMLPort(Element& xmlElement, XMLPort::Mode mode)
     58    void ResourceLocation::XMLPort(Element& xmlelement, XMLPort::Mode mode)
    5959    {
    60         XMLPortParam(ResourceLocation, "path",        setPath,        getPath,        xmlElement, mode);
    61         XMLPortParam(ResourceLocation, "archiveType", setArchiveType, getArchiveType, xmlElement, mode);
    62         XMLPortParam(ResourceLocation, "recursive",   setRecursive,   getRecursive,   xmlElement, mode);
     60        XMLPortParam(ResourceLocation, "path",        setPath,        getPath,        xmlelement, mode);
     61        XMLPortParam(ResourceLocation, "archiveType", setArchiveType, getArchiveType, xmlelement, mode);
     62        XMLPortParam(ResourceLocation, "recursive",   setRecursive,   getRecursive,   xmlelement, mode);
    6363        if (path_.empty())
    6464            ThrowException(AbortLoading, "ResourceLocation: No path given.");

  • code/trunk/src/libraries/tools/ResourceLocation.h

    r5781 r7401  
    4646        virtual ~ResourceLocation();
    4747
    48         virtual void XMLPort(Element& xmlElement, XMLPort::Mode mode);
     48        virtual void XMLPort(Element& xmlelement, XMLPort::Mode mode);
    4949
    5050        void setPath(const std::string& path) { path_ = path; }

  • code/trunk/src/libraries/tools/Timer.cc

    r7284 r7401  
    2727 */
    2828
     29/**
     30    @file
     31    @brief Implementation of the Timer class.
     32*/
     33
    2934#include "Timer.h"
    3035
    … …  
    4550
    4651    /**
    47         @brief Calls a console command after 'delay' seconds.
     52        @brief Console-command: Calls another console command after @a delay seconds.
    4853        @param delay The delay in seconds
    4954        @param command The console command
    … …  
    6065
    6166    /**
    62         @brief Executes the command.
    63         @param timer The timer to destroy after the command-execution
     67        @brief Helper function for delay(), executes the command and destroys the timer.
     68        @param timer The timer which called this function.
    6469        @param command The command to execute
    6570    */
    … …  
    7277
    7378    /**
    74         @brief Kills all delayed commands.
     79        @brief Console-command: Kills all scheduled commands that were delayed using delay().
    7580    */
    7681    void killdelays()
    … …  
    9297
    9398    /**
    94         @brief Constructor: Initializes the Timer with given values.
    95         @param interval The timer-interval in seconds
    96         @param bLoop If true, the function gets called every 'interval' seconds
    97         @param exeuctor A executor of the function to call
     99        @brief Constructor: Initializes and starts the timer, which will call an executor after some time.
     100        @param interval         The timer-interval in seconds
     101        @param bLoop            If true, the executor gets called every @a interval seconds
     102        @param executor         The executor that will be called
     103        @param bKillAfterCall   If true, the timer will be deleted after the executor was called
    98104    */
    99105    Timer::Timer(float interval, bool bLoop, const ExecutorPtr& executor, bool bKillAfterCall)
    … …  
    120126
    121127    /**
    122         @brief Executes the executor.
     128        @brief Calls the executor and destroys the timer if requested.
    123129    */
    124130    void Timer::run()

  • code/trunk/src/libraries/tools/Timer.h

    r7284 r7401  
    2727 */
    2828
    29 /*!
     29/**
     30    @defgroup Timer Timer
     31    @ingroup Tools
     32*/
     33
     34/**
    3035    @file
    31     @brief Definition and Implementation of the Timer class.
     36    @ingroup Timer
     37    @brief Declaration of the Timer class, used to call functions after a given time-interval.
    3238
    33     The Timer is a callback-object, calling a given function after a given time-interval.
     39    @anchor TimerExample
    3440
    35     Usage:
     41    Timer is a helper class that executes a function after a given amount of time.
     42
     43    Usage: <br>
    3644    header.h:
    37         class ClassName
    38         {
    39             public:
    40                 ClassName();
    41                 void functionName();
    42                 Timer myTimer;
    43         };
     45    @code
     46    class MyClass
     47    {
     48        public:
     49            MyClass();
     50            void functionName();
     51
     52        private:
     53            Timer myTimer;
     54    };
     55    @endcode
    4456
    4557    source.cc:
    46         #include "core/command/Executor.h"
     58    @code
     59    #include "core/command/Executor.h"
    4760
    48         ClassName::ClassName()
    49         {
    50             myTimer.setTimer(interval_in_seconds, bLoop, createExecutor(createFunctor(&ClassName::functionName, this)));
    51         }
     61    MyClass::MyClass()
     62    {
     63        myTimer.setTimer(3, false, createExecutor(createFunctor(&ClassName::myFunction, this)));
     64    }
    5265
    53         void ClassName::functionName()
    54         {
    55             whateveryouwant();
    56             something(else);
    57         }
     66    void MyClass::myFunction()
     67    {
     68        COUT(0) << "Hello World" << std::endl;
     69    }
     70    @endcode
     71
     72    The code in this example prints "Hello World" to the console, 3 seconds after creating
     73    an instance of MyClass.
    5874*/
    5975
    … …  
    7389    void executeDelayedCommand(Timer* timer, const std::string& command);
    7490
    75     //! The Timer is a callback-object, calling a given function after a given time-interval.
     91    /**
     92        @brief Timer is a helper class that executes a function after a given amount of time.
     93
     94        @see See @ref TimerExample "Timer.h" for an example.
     95    */
    7696    class _ToolsExport Timer : public TimeFactorListener
    7797    {
    … …  
    82102
    83103            /**
    84                 @brief Initializes the Timer with given values.
    85                 @param interval The timer-interval in seconds
    86                 @param bLoop If true, the function gets called every 'interval' seconds
    87                 @param object The object owning the timer and the function
    88                 @param executor A executor of the function to call
     104                @brief Initializes and starts the timer, which will call an executor after some time.
     105                @param interval         The timer-interval in seconds
     106                @param bLoop            If true, the executor gets called every @a interval seconds
     107                @param executor         The executor that will be called
     108                @param bKillAfterCall   If true, the timer will be deleted after the executor was called
    89109            */
    90110            void setTimer(float interval, bool bLoop, const ExecutorPtr& executor, bool bKillAfterCall = false)
    … …  
    101121            void run();
    102122
    103             /** @brief Starts the Timer: Function-call after 'interval' seconds. */
     123            /// Re-starts the Timer: The executor will be called after @a interval seconds.
    104124            inline void startTimer()
    105125                { this->bActive_ = true; this->time_ = this->interval_; }
    106             /** @brief Stops the Timer. */
     126            /// Stops the Timer.
    107127            inline void stopTimer()
    108128                { this->bActive_ = false; this->time_ = this->interval_; }
    109             /** @brief Pauses the Timer - it will continue with the actual state if you unpause it. */
     129            /// Pauses the Timer - it will continue with the actual state if you call unpauseTimer().
    110130            inline void pauseTimer()
    111131                { this->bActive_ = false; }
    112             /** @brief Unpauses the Timer - continues with the given state. */
     132            /// Unpauses the Timer - continues with the given state.
    113133            inline void unpauseTimer()
    114134                { this->bActive_ = true; }
    115             /** @brief Returns true if the Timer is active (= not stoped, not paused). @return True = Time is active */
     135            /// Returns true if the Timer is active (neither stoped nor paused).
    116136            inline bool isActive() const
    117137                { return this->bActive_; }
    118             /** @brief Returns the remaining time until the Timer calls the function. @return The remaining time */
     138            /// Returns the remaining time until the Timer calls the executor.
    119139            inline float getRemainingTime() const
    120140                { return static_cast<float>(this->time_ / 1000000.0f); }
    121             /** @brief Gives the Timer some extra time. @param time The amount of extra time in seconds */
     141            /// Increases the remaining time of the Timer by the given amount of time (in seconds).
    122142            inline void addTime(float time)
    123143                { if (time > 0.0f) this->time_ += static_cast<long long>(time * 1000000.0f); }
    124             /** @brief Decreases the remaining time of the Timer. @param time The amount of time to remove */
     144            /// Decreases the remaining time of the Timer by the given amount of time (in seconds)
    125145            inline void removeTime(float time)
    126146                { if (time > 0.0f) this->time_ -= static_cast<long long>(time * 1000000.0f); }
    127             /** @brief Sets the interval of the Timer. @param interval The interval */
     147            /// Changes the calling interval.
    128148            inline void setInterval(float interval)
    129149                { this->interval_ = static_cast<long long>(interval * 1000000.0f); }
    130             /** @brief Sets bLoop to a given value. @param bLoop True = loop */
     150            /// Defines if the timer call the executor every @a interval seconds or only once.
    131151            inline void setLoop(bool bLoop)
    132152                { this->bLoop_ = bLoop; }
    … …  
    137157            void init();
    138158
    139             ExecutorPtr executor_;  //!< The executor of the function that should be called when the time expires
     159            ExecutorPtr executor_;  //!< The executor of the function that will be called when the time expires
    140160
    141161            long long interval_;    //!< The time-interval in micro seconds
    142             bool bLoop_;            //!< If true, the function gets called every 'interval' seconds
    143             bool bActive_;          //!< If true, the Timer ticks and calls the function if the time's up
    144             bool bKillAfterCall_;   //!< If true the timer gets deleted after it called the function
     162            bool bLoop_;            //!< If true, the executor gets called every @a interval seconds
     163            bool bActive_;          //!< If true, the Timer ticks and calls the executor if the time's up
     164            bool bKillAfterCall_;   //!< If true the timer gets deleted after it expired and called the executor
    145165
    146             long long time_;        //!< Internal variable, counting the time till the next function-call
     166            long long time_;        //!< Internal variable, counting the time untill the next executor-call
    147167    };
    148168}

  • code/trunk/src/libraries/util/Clipboard.cc

    r6417 r7401  
    5454
    5555    /**
    56         @brief Puts text into the windows-clipboard
    57         @param text The text
     56        @brief Puts text into the Windows-clipboard
    5857        @return True if the action was successful
    5958    */
    … …  
    119118namespace orxonox
    120119{
    121     static std::string clipboard; //!< Keeps the text of our internal clipboard
     120    static std::string clipboard; ///< Keeps the text of our internal clipboard
    122121
    123122    /**
    124123        @brief Default implementation if there is no OS-specific implementation or no clipboard. Copies the text into an internal clipboard.
    125         @param text The text
    126         @return True
     124        @see fromClipboard()
    127125    */
    128126    bool toClipboard(const std::string& text)
    … …  
    134132    /**
    135133        @brief Default implementation if there is no OS-specific implementation or no clipboard. Gets the text from the internal clipboard.
    136         @return The text
     134        @see toClipboard()
    137135    */
    138136    std::string fromClipboard()

  • code/trunk/src/libraries/util/Clipboard.h

    r5781 r7401  
    2929/**
    3030    @file
    31     @brief Some functions to exchange text between the OS clipboard and Orxonox.
     31    @ingroup Util Command
     32    @brief Some functions to exchange text between the OS clipboard and the Shell in Orxonox.
    3233
    3334    Use fromClipboard() to get text from the clipboard (if there is any text) and
    34     toClipboard(text) to put text into the clipboard.
     35    toClipboard() to put text into the clipboard.
    3536
    36     Those functions can only work properly if there's an OS-specific implementation.
    37     If an OS isn't supported, the clipboard only works within Orxonox, but exchange
    38     with other programs isn't possible.
     37    These functions can only work properly if there's an OS-specific implementation
     38    in Clipboard.cc. If a specific OS is not supported, the clipboard only works
     39    within Orxonox, but the exchange with other programs is not possible.
    3940*/
    4041

  • code/trunk/src/libraries/util/Clock.cc

    r6417 r7401  
    4545    }
    4646
    47     /**
    48     @remarks
    49         Mind the types! Ogre::Timer::getMicroseconds() will return an unsigned
    50         long, which will eventually overflow. But if you use the subtraction of
    51         the current time minus the last time the timer gave us and sum these up to
    52         a 64 bit integer, we get the desired result.
    53         Also mind that we don't have to store the last timer's time as unsigned long
    54         as well because (unsigned long)tickTime_ will do exactly that.
    55     */
    5647    void Clock::capture()
    5748    {

  • code/trunk/src/libraries/util/Clock.h

    r6417 r7401  
    2727 */
    2828
     29/**
     30    @file
     31    @ingroup Util
     32*/
     33
    2934#ifndef _Clock_H__
    3035#define _Clock_H__
    … …  
    3540namespace orxonox
    3641{
     42    /** Simple real time clock based on Ogre::Timer
     43    @details
     44        The class can be used to both capture the current real time or to
     45        incrementally capture the time and then distribute that time information
     46        via Clock& references (for instance for the game tick). <br>
     47        Precision: <br>
     48    @par Precision
     49        The maximum precision is given by the Ogre::Timer and that is somewhere
     50        in the microsecond range for both Windows and UNIX.
     51    @par Remarks for Usage on Windows
     52        For proper functionality this class MUST be used in the same thread! <br>
     53        Furthermore it might be possible that the Ogre::Timer has a performance
     54        caveat because it will only capture the time on the same CPU core.
     55        Confining the main thread to one process could speed up the game.
     56        See \ref cmdargspage "Ccommandline Argument" 'limitToCPU' (only on Windows)
     57    */
    3758    class _UtilExport Clock
    3859    {
    3960    public:
     61        /// Starts the time at 0
    4062        Clock();
    4163        ~Clock();
    4264
     65        /** Internally captures the time and stays at that particular time
     66        @remarks
     67            Mind the types! Ogre::Timer::getMicroseconds() will return an unsigned
     68            long, which will eventually overflow. But if you use the subtraction of
     69            the current time minus the last time the timer gave us and sum these up to
     70            a 64 bit integer, we get the desired result. <br>
     71            Also mind that we don't have to store the last timer's time as unsigned long
     72            as well because (unsigned long)tickTime_ will do exactly that.
     73        */
    4374        void capture();
    4475
    45         unsigned long long getMicroseconds()   const { return tickTime_; }
    46         unsigned long long getMilliseconds()   const { return tickTime_ / 1000; }
    47         unsigned long      getSeconds()        const { return static_cast<long> (tickTime_ / 1000000); }
    48         float              getSecondsPrecise() const { return static_cast<float>(tickTime_ / 1000000.0f); }
     76        /// Returns the last captured absolute time in microseconds
     77        unsigned long long getMicroseconds() const
     78            { return tickTime_; }
     79        /// Returns the last captured absolute time in milliseconds
     80        unsigned long long getMilliseconds() const
     81            { return tickTime_ / 1000; }
     82        /// Returns the last captured absolute time in seconds
     83        unsigned long getSeconds() const
     84            { return static_cast<long> (tickTime_ / 1000000); }
     85        /// Returns the last captured absolute time in seconds as float
     86        float getSecondsPrecise() const
     87            { return static_cast<float>(tickTime_ / 1000000.0f); }
    4988
    50         float              getDeltaTime()      const { return tickDtFloat_; }
    51         long               getDeltaTimeMicroseconds() const { return tickDt_; }
     89        /// Returns the timespan in seconds between the last two calls to capture()
     90        float getDeltaTime() const
     91            { return tickDtFloat_; }
     92        /// Returns the timespan in microseconds between the last two calls to capture()
     93        long getDeltaTimeMicroseconds() const
     94            { return tickDt_; }
    5295
     96        /** Returns the current real time in microseconds
     97        @note
     98            This is especially useful to measure execution times because of the
     99            high precision.
     100        */
    53101        unsigned long long getRealMicroseconds() const;
    54102
    55103    private:
     104        /// Undefined
    56105        Clock(const Clock& instance);
    57106
    58         Ogre::Timer*       timer_;
    59         unsigned long long tickTime_;
    60         long               tickDt_;
    61         float              tickDtFloat_;
     107        Ogre::Timer*       timer_;       ///< Ogre timer object
     108        unsigned long long tickTime_;    ///< Currently captured time
     109        long               tickDt_;      ///< Delta time in microseconds (cache value)
     110        float              tickDtFloat_; ///< Delta time in seconds (cache value)
    62111    };
    63112}

  • code/trunk/src/libraries/util/Convert.cc

    r7163 r7401  
    3232namespace orxonox
    3333{
    34     //template <class FromType, class ToType>
    3534    bool ConverterExplicit<std::string, bool>::convert(bool* output, const std::string& input)
    3635    {

  • code/trunk/src/libraries/util/Convert.h

    r7305 r7401  
    2828 */
    2929
    30 /*!
    31     @file
    32     @brief Definition and Implementation of the Convert class.
     30/**
     31    @defgroup Convert Conversion functions
     32    @ingroup Util
     33*/
     34
     35/** Functions that convert values between different types.
     36@file
     37@ingroup Convert
     38@par Usage
     39    There are three ways to use the conversions depending on what you need. <br>
     40    - For simply converting values without having to know whether the conversion
     41      was successful (for instance float --> string), use orxonox::multi_cast
     42      which effectively works exactly like static_cast, etc.
     43      @code
     44        float input = 42.0;
     45        std::string output = multi_cast<std::string>(input);
     46      @endcode
     47    - If you care about whether the conversion was successful,
     48      use orxonox::convertValue.
     49      @code
     50        std::string input("3.4");
     51        float output;
     52        bool success = convertValue(&output, input);
     53      @endcode
     54    - If you care about success and if you can also feed a fallback value,
     55      use orxonox::convertValue.
     56      @code
     57        std::string input("3.4");
     58        float output;
     59        bool success = convertValue(&output, input, 0.0);
     60      @endcode
     61    - If success doesn't matter but you can feed a fallback value,
     62      use orxonox::getConvertedValue.
     63      @code
     64        std::string input("3.4");
     65        float output = getConvertedValue(input, 0.0);
     66      @endcode
     67@details
     68    The back end of these functions are the actual implementations for the
     69    specific conversions, for instance from Ogre::Vector3 to std::string and
     70    vice versa. Some of them also use the iostream operators. <br>
     71    The real deal is evaluating which function is needed for a conversion based
     72    on the input and output type. But there are lots of catches in conjunction
     73    with templates which explains why there are so many functions in this file.
     74    <br> <br>
     75@par Search Order
     76    Finding the right function is governed by priority rules: <br>
     77    -# (Partial) template specialisation of orxonox::ConverterExplicit::convert()
     78    -# An implicit conversion. This includes 'FooBar' to 'int' if FooBar
     79       defines operator int() or float().
     80    -# Global or member operators for iostream when converting from or
     81       to std::string (and FROM const char*)
     82    -# (Partial) template specialisation of orxonox::ConverterFallback::convert()
     83    -# Fallback function that displays "Could not convert value" with type
     84       information obtained from typeid().
     85@par Implementing conversion functions
     86    To do that you probably need to know a thing or two about the types
     87    involved. So, get ready with that. <br>
     88    Usually the best way to do it is specialising of the orxonox::ConverterFallback
     89    template, like this:
     90    @code
     91    template <>
     92    struct _UtilExport ConverterFallback<std::string, MyType>
     93    {
     94        static bool convert(MyType* output, const std::string& input)
     95        {
     96           ...
     97           return success;
     98        }
     99    };
     100    @endcode
     101    This piece of code converts an std::string to MyType and returns whether the
     102    conversion was successful. You can also use partial specialisation.<br>
     103    The advantage with orxonox::ConverterFallback is that it has a low priority
     104    meaning that when there is an implicit conversion or an iostream method, that
     105    comes first and you don't have to deal with it (and the accompanying
     106    function call ambiguity). <br>
     107    However sometimes you would like to explicitely replace such a conversion.
     108    That's where orxonox::ConverterExplicit comes in handy (for instance we
     109    replaced the operator << conversions for Ogre::VectorX with our own functions).
     110@note
     111    There has to be an exact type match when using template specialisations. <br>
     112    Template specialisations can be defined after including this file.
     113    But any implicit cast function or iostream operator has to be included
     114    in this file!
     115@par Understanding the Code
     116    In order to understand how the templates work, it is probably best to study
     117    the functions in order of calling. There are lots of comments explaining
     118    what happens, but you'll need to understand a deal about partial template
     119    specialisation and function headers are matched in C++.
    33120*/
    34121
    … …  
    46133#include "ImplicitConversion.h"
    47134
    48 ////////////////////////////////////
    49 //// ACTUAL CONVERSION SEQUENCE ////
    50 ////////////////////////////////////
    51 /*
    52     There is a distinct priority when choosing the right conversion function:
    53     Overwrite:
    54     1. (Partial) template specialisation of ConverterExplicit::convert()
    55     Fallbacks:
    56     2. Any possible implicit conversion. This includes 'FooBar' --> 'int' if FooBar defines operator float().
    57     3. Global or member operators for stringstream when converting from or to std::string (or FROM const char*)
    58     4. (Partial) template specialisation of ConverterFallback::convert()
    59     5. Function that simply displays "Could not convert value" with type information obtained from typeid().
    60 
    61     Notes:
    62     There has to be an exact type match when using template specialisations.
    63     Template specialisations can be defined after including this file. Any implicit cast function or iostream
    64     operator has to be declared BEFORE this file gets parsed.
    65 
    66     Defining your own functions:
    67     There are obviously 4 ways to specify a user defined conversion. What should you use?
    68 
    69     Usually, ConverterFallback fits quite well. You won't have to deal with the conversion from
    70     'MyClass' to 'MyClass' by using another explicit template specialisation to avoid ambiguities.
    71 
    72     However if you want to overwrite an implicit conversion or an iostream operator, you really need to
    73     make use of ConverterExplicit. We have to do this for the Ogre classes for instance because they
    74     define stream operators we don't particulary like.
    75 */
    76 
    77135namespace orxonox
    78136{
    … …  
    81139    ///////////////////
    82140
    83     // Default template. No conversion available at all.
     141    /// Default template. No conversion available at all.
    84142    template <class FromType, class ToType>
    85143    struct ConverterFallback
    … …  
    93151    };
    94152
    95     // If all else fails, try a dynamic_cast for pointer types.
     153    /// If all else fails, try a dynamic_cast for pointer types.
    96154    template <class FromType, class ToType>
    97155    struct ConverterFallback<FromType*, ToType*>
    … …  
    109167        }
    110168    };
    111 
    112     ////////////
    113     // upcast //
    114     ////////////
    115     namespace detail
    116     {
    117         // perform a static cast if ToType is a base of FromType
    118         template<class ToType, class FromType>
    119         FORCEINLINE ToType upcast(FromType input, Loki::Int2Type<true>)
    120         {
    121             return static_cast<ToType>(input);
    122         }
    123 
    124         // return zero if ToType is not a base of FromType
    125         template<class ToType, class FromType>
    126         FORCEINLINE ToType upcast(FromType input, Loki::Int2Type<false>)
    127         {
    128             return 0;
    129         }
    130     }
    131 
    132     // performs an upcast if ToType is a base of FromType, returns zero otherwise
    133     template <class ToType, class FromType>
    134     FORCEINLINE ToType upcast(FromType input)
    135     {
    136         enum { probe = ImplicitConversion<FromType, ToType>::exists };
    137         return detail::upcast<ToType, FromType>(input, Loki::Int2Type<probe>());
    138     }
    139169}
    140170
    … …  
    144174///////////////////////
    145175
    146 // Default template for stringstream
     176/** Fallback template for stringstream
     177@details
     178    Neither FromType nor ToType was std::string, therefore
     179    delegate to orxonox::ConverterFallback
     180*/
    147181template <class FromType, class ToType>
    148182struct ConverterStringStream
    … …  
    159193/////////////
    160194
     195/// Extra namespace to avoid exposing the iostream operators in it
    161196namespace fallbackTemplates
    162197{
     198    /// Fallback operator <<() (delegates to orxonox::ConverterFallback)
    163199    template <class FromType>
    164200    FORCEINLINE bool operator <<(std::ostream& outstream,  const FromType& input)
    … …  
    175211}
    176212
    177 // template that evaluates whether we can convert to std::string via ostringstream
     213/// Template that evaluates whether we can convert to std::string via ostringstream
    178214template <class FromType>
    179215struct ConverterStringStream<FromType, std::string>
    … …  
    182218    {
    183219        using namespace fallbackTemplates;
    184         // this operator call only chooses fallbackTemplates::operator<< if there's no other fitting function
     220        // this operator call only chooses fallbackTemplates::operator<<()
     221        // if there's no other fitting function
    185222        std::ostringstream oss;
     223        // Note: std::ostream has operator!() to tell whether any error flag was set
    186224        if (oss << input)
    187225        {
    … …  
    201239namespace fallbackTemplates
    202240{
     241    /// Fallback operator >>() (delegates to orxonox::ConverterFallback)
    203242    template <class ToType>
    204243    FORCEINLINE bool operator >>(std::istream& instream, ToType& output)
    205244    {
    206         return orxonox::ConverterFallback<std::string, ToType>
    207             ::convert(&output, static_cast<std::istringstream&>(instream).str());
     245        std::string input(static_cast<std::istringstream&>(instream).str());
     246        return orxonox::ConverterFallback<std::string, ToType>::convert(&output, input);
    208247    }
    209248}
    210249
    211 // template that evaluates whether we can convert from std::string via ostringstream
     250/// Template that evaluates whether we can convert from std::string via istringstream
    212251template <class ToType>
    213252struct ConverterStringStream<std::string, ToType>
    … …  
    216255    {
    217256        using namespace fallbackTemplates;
     257        // this operator call chooses fallbackTemplates::operator>>()
     258        // only if there's no other fitting function
    218259        std::istringstream iss(input);
    219         // this operator call only chooses fallbackTemplates::operator>> if there's no other fitting function
     260        // Note: std::istream has operator!() to tell whether any error flag was set
    220261        if (iss >> (*output))
    221262        {
    … …  
    229270namespace orxonox
    230271{
    231 
    232272    ///////////////////
    233273    // Implicit Cast //
    234274    ///////////////////
    235275
    236     // implicit cast not possible, try stringstream conversion next
     276    /// %Template delegates to ::ConverterStringStream
    237277    template <class FromType, class ToType>
    238278    FORCEINLINE bool convertImplicitely(ToType* output, const FromType& input, Loki::Int2Type<false>)
    … …  
    241281    }
    242282
    243     // We can cast implicitely
     283    /// Makes an implicit cast from \a FromType to \a ToType
    244284    template <class FromType, class ToType>
    245285    FORCEINLINE bool convertImplicitely(ToType* output, const FromType& input, Loki::Int2Type<true>)
    … …  
    254294    ////////////////////////////////
    255295
    256     // Default template if no specialisation is available
     296    /** Default template if no orxonox::ConverterExplicit is available
     297    @details
     298        Evaluates whether \a FromType can be implicitly converted to \a ToType
     299        by the use the ImplicitConversion magic.
     300    */
    257301    template <class FromType, class ToType>
    258302    struct ConverterExplicit
    … …  
    261305        FORCEINLINE static bool convert(ToType* output, const FromType& input)
    262306        {
    263             // Try implict cast and probe first. If a simple cast is not possible, it will not compile
    264             // We therefore have to out source it into another template function
     307            // Use the probe's value to delegate to the right function
    265308            return convertImplicitely(output, input, Loki::Int2Type<probe>());
    266309        }
    … …  
    275318    @brief
    276319        Converts any value to any other as long as there exists a conversion.
     320    @details
    277321        Otherwise, the conversion will generate a runtime warning and return false.
    278         For information about the different conversion methods (user defined too), see the section
    279         'Actual conversion sequence' in this file above.
     322    @see Convert.h
     323    @param output
     324        A pointer to the variable where the converted value will be stored
     325    @param input
     326        The original value
    280327    */
    281328    template <class FromType, class ToType>
    … …  
    291338        Converts any value to any other as long as there exists a conversion.
    292339        Otherwise, the conversion will generate a runtime warning and return false.
    293         For information about the different conversion methods (user defined too), see the section
    294         'Actual conversion sequence' in this file above.
    295         If the conversion doesn't succeed, 'fallback' is written to '*output'.
     340        If the conversion doesn't succeed, \a fallback is written to \a output.
     341    @see Convert.h
     342    @param output
     343        A pointer to the variable where the converted value will be stored
     344    @param input
     345        The original value
    296346    @param fallback
    297347        A default value that gets written to '*output' if there is no conversion.
    … …  
    309359    }
    310360
    311     // Directly returns the converted value, even if the conversion was not successful.
     361    /// Directly returns the converted value, but uses the fallback on failure. @see convertValue
    312362    template<class FromType, class ToType>
    313     FORCEINLINE ToType getConvertedValue(const FromType& input)
     363    FORCEINLINE ToType getConvertedValue(const FromType& input, const ToType& fallback)
     364    {
     365        ToType output;
     366        convertValue(&output, input, fallback);
     367        return output;
     368    }
     369
     370    /**
     371    @brief
     372        Converts any value to any other as long as there exists a conversion.
     373    @details
     374        Use exactly the way you use static_cast, etc. <br>
     375        A failed conversion will return a default instance of \a ToType
     376        (possibly uninitialised)
     377    @see Convert.h
     378    @param input
     379        The original value
     380    */
     381    template<class ToType, class FromType>
     382    FORCEINLINE ToType multi_cast(const FromType& input)
    314383    {
    315384        ToType output;
    … …  
    318387    }
    319388
    320     // Directly returns the converted value, but uses the fallback on failure.
    321     template<class FromType, class ToType>
    322     FORCEINLINE ToType getConvertedValue(const FromType& input, const ToType& fallback)
    323     {
    324         ToType output;
    325         convertValue(&output, input, fallback);
    326         return output;
    327     }
    328 
    329     // Like getConvertedValue, but the template argument order is in reverse.
    330     // That means you can call it exactly like static_cast<ToType>(fromTypeValue).
    331     template<class ToType, class FromType>
    332     FORCEINLINE ToType multi_cast(const FromType& input)
    333     {
    334         ToType output;
    335         convertValue(&output, input);
    336         return output;
    337     }
    338 
    339389    ////////////////////////////////
    340390    // Special string conversions //
    341391    ////////////////////////////////
    342392
    343     // Delegate conversion from const char* to std::string
     393    /// Delegates conversion from const char* to std::string
    344394    template <class ToType>
    345395    struct ConverterExplicit<const char*, ToType>
    … …  
    351401    };
    352402
    353     // These conversions would exhibit ambiguous << or >> operators when using stringstream
     403    /// Conversion would exhibit ambiguous << or >> operators when using iostream
    354404    template <>
    355405    struct ConverterExplicit<char, std::string>
    … …  
    361411        }
    362412    };
     413    /// Conversion would exhibit ambiguous << or >> operators when using iostream
    363414    template <>
    364415    struct ConverterExplicit<unsigned char, std::string>
    … …  
    370421        }
    371422    };
     423    /// Conversion would exhibit ambiguous << or >> operators when using iostream
    372424    template <>
    373425    struct ConverterExplicit<std::string, char>
    … …  
    382434        }
    383435    };
     436    /// Conversion would exhibit ambiguous << or >> operators when using iostream
    384437    template <>
    385438    struct ConverterExplicit<std::string, unsigned char>
    … …  
    396449
    397450
    398     // bool to std::string
     451    /// Conversion from bool to std::string
    399452    template <>
    400453    struct ConverterExplicit<bool, std::string>
    … …  
    410463    };
    411464
    412     // std::string to bool
     465    /// Conversion from std::string to bool
    413466    template <>
    414467    struct _UtilExport ConverterExplicit<std::string, bool>

  • code/trunk/src/libraries/util/Debug.h

    r6443 r7401  
    2929
    3030/**
     31    @defgroup COUT COUT(x) output macro
     32    @ingroup Util
     33*/
     34
     35/**
    3136@file
     37@ingroup COUT
    3238@brief
    33     Handles different output-levels of errors, warnings, infos and debug information.
     39    Handles different output-levels of errors, warnings, infos, and debug information.
    3440
    35     The COUT(level) macro acts like std::cout, but the output is only performed if the given
     41    The COUT(level) macro acts like @c std::cout, but the output is only performed if the given
    3642    level is <= the soft debug level.
    3743
    … …  
    3945     - The hard debug level is used during compile time. It describes the highest allowed output level.
    4046     - The soft debug level is used during runtime and is the maximum of the three configurable
    41        output-levels for console, log file and in game shell.
     47       output-levels for console, log file, and in game shell.
    4248
    4349    The separation between the three devices is done by the OutputHandler.
    4450
     51    @anchor COUTlevels
    4552    Possible levels are:
    46      0: Very important output
    47      1: Errors
    48      2: Warnings
    49      3: Information
    50      4: Debug information
    51      5: More debug information
    52      6: Crazy debug information
     53     - 0: Very important output
     54     - 1: Errors
     55     - 2: Warnings
     56     - 3: Information
     57     - 4: Debug information
     58     - 5: More debug information
     59     - 6: Crazy debug information
    5360
    54 @example
     61    Example:
     62    @code
    5563    COUT(0) << "Very important output" << std::endl;
    5664    COUT(1) << "Error: Something went wrong!" << std::endl;
    … …  
    5866    COUT(3) << "Info: It's Monday" << std::endl;
    5967    COUT(4) << "Debug: x is 1.23456" << std::endl;
     68    @endcode
    6069*/
    6170
    … …  
    9099/**
    91100@brief
    92     Logs text output: use exactly like std::cout, but specify an output
    93     level as argument.
    94 @details
    95     (a > b ? 0 : c << "text") is equivalent to (a > b ? 0 : (c << "text"))
    96     where (a > b ? 0 : ) stands for COUT(x). This should explain how
     101    Logs text output: You can use COUT(level) exactly like @c std::cout, but you have to specify an output level as argument.
     102@param level
     103    The level of the following output (passed with <tt><< "text"</tt>). Lower levels are more important. See @ref COUTlevels "the description above" for a list of possible output levels.
     104
     105    Example:
     106    @code
     107    COUT(3) << "Some info" << std::endl; // Output with level 3
     108    @endcode
     109@note
     110    <tt>(a > b ? 0 : c << "text")</tt> is equivalent to <tt>(a > b ? 0 : (c << "text")</tt>
     111    where <tt>(a > b ? 0 : )</tt> stands for COUT(x). This should explain how
    97112    this macro magic can possibly even work ;)
    98 @example
    99     COUT(3) << "Some info" << std::endl;
    100 @note
    101     The ? : operator requires both possible results to have the type of
     113@remarks
     114    The <tt>? :</tt> operator requires both possible results to have the type of
    102115    the first. This is achieved by the int conversion operator dummy
    103     in the OutputHandler.
     116    in the @ref orxonox::OutputHandler.
    104117*/
    105118#define COUT(level)                                                    \

  • code/trunk/src/libraries/util/Exception.cc

    r7174 r7401  
    5353    { }
    5454
    55     /**
    56     @remarks
    57         The composed full description gets stored to fullDescription_. But for compliance
    58         with std::exception, this method has to be const. Hence fullDescription_ is declared
    59         as mutable.
    60     */
    6155    const std::string& Exception::getFullDescription() const
    6256    {
    … …  
    8983    }
    9084
    91     //! Returns the error description
    9285    const char* Exception::what() const throw()
    9386    {

  • code/trunk/src/libraries/util/Exception.h

    r6417 r7401  
    2828
    2929/**
     30    @defgroup ExceptionAssertion Exceptions and assertions
     31    @ingroup Util
     32*/
     33
     34/**
    3035@file
     36@ingroup ExceptionAssertion
    3137@brief
    3238    Declaration of facilities to handle exceptions.
     39@details
     40    Any exception thrown should inherit from orxonox::Exception. There is a macro
     41    \ref CREATE_ORXONOX_EXCEPTION to create a new exception (you can find a list of
     42    available exceptions in the docs of this file). <br>
     43    Throwing exception is also very simple:
     44    @code
     45        ThrowException(General, "Something went wrong");
     46    @endcode
     47    (\c General is a type of exception, see docs of this file) <br>
     48    The exception will automatically contain information about file, line number
     49    and function name it occurred in. <br><br>
     50    There is also some magic you can do for numbers, etc.:
     51    @code
     52        ThrowException(General, "Error code: " << myInt << ". more info...");
     53    @endcode
     54    It works with an std::ostringstream, so you can feed it all sorts of values.
    3355*/
    3456
    … …  
    4567namespace orxonox
    4668{
    47     /**
    48     @brief
    49         Base class for all exceptions (derived from std::exception).
     69    /** Base class for all exceptions (derived from std::exception).
    5070    @details
    5171        This class provides support for information about the file, the line
    52         and the function the error occured.
     72        and the function the error occurred.
     73    @see Exception.h
    5374    */
    5475    class _UtilExport Exception : public std::exception
    … …  
    6081        @param description
    6182            Exception description as string. This message is supposed to help developers!
     83        @param lineNumber
     84            The number of the code-line in which the exception occurred
     85        @param filename
     86            The file in which the exception occurred
     87        @param functionName
     88            The function in which the exception occurred
    6289        */
    6390        Exception(const std::string& description, unsigned int lineNumber,
    … …  
    6895        //! Needed for compatibility with std::exception
    6996        virtual ~Exception() throw() { }
     97        //! Returns the error description
    7098        const char* what() const throw();
    7199
    72         //! Returns a full description with type, line, file and function
     100        /** Returns a full description with type, line, file and function
     101        @remarks
     102            The composed full description gets stored to fullDescription_. But for compliance
     103            with std::exception, this method has to be const. Hence fullDescription_ is declared
     104            as mutable.
     105        */
    73106        virtual const std::string& getFullDescription() const;
    74107        //! Returns the string name of the exception type
    … …  
    101134    };
    102135
    103 //! Creates a new type of exception that inherits from tracker::Exception
     136//! Creates a new type of exception that inherits from orxonox::Exception
    104137#define CREATE_ORXONOX_EXCEPTION(ExceptionName)                                     \
    105138    class ExceptionName##Exception : public Exception                               \
    … …  
    123156    // Creates all possible exception types.
    124157    // If you want to add a new type, simply copy and adjust a new line here.
    125 #ifndef DOXYGEN_SHOULD_SKIP_THIS
    126158    CREATE_ORXONOX_EXCEPTION(General);
    127159    CREATE_ORXONOX_EXCEPTION(FileNotFound);
    … …  
    136168    CREATE_ORXONOX_EXCEPTION(NoGraphics);
    137169    CREATE_ORXONOX_EXCEPTION(AbortLoading);
    138 #endif
    139170
    140     /**
    141     @brief
    142         Helper function that forwards an exception and displays the message.
     171    /** Helper function that forwards an exception and displays the message.
    143172    @details
    144173        This is necessary because only when using 'throw' the objects storage is managed.
    … …  
    152181    }
    153182
    154 /**
    155 @brief
    156     Throws an exception and logs a message beforehand.
     183/** Throws an exception and logs a message beforehand.
    157184@param type
    158185    Type of the exception as literal (General, Initialisation, etc.)
    159186@param description
    160187    Exception description as string
     188@see Exception.h
    161189*/
    162190#define ThrowException(type, description) \

  • code/trunk/src/libraries/util/ExprParser.h

    r6417 r7401  
    2828
    2929/**
    30   @file
    31   @brief Declaration of FloatParser
     30@file
     31@ingroup Util
     32@brief Declaration of FloatParser
    3233*/
    3334
    … …  
    4243namespace orxonox
    4344{
     45    /** Parser for expressions like \c "3 * cos(5 + 4) / a" where \a a is a predeclared
     46        variable.
     47    @par Usage
     48        Using it is rather simple:
     49        @code
     50        std::string str("3 + 4");
     51        ExprParser expr;
     52        expr.parse(str);
     53        if (expr.getSuccess())
     54        {
     55            if (!expr.getRemains().empty())
     56            {
     57                COUT(2) << "Warning: Expression could not be parsed to the end! Remains: '" << expr.getRemains() << '\'' << std::endl;
     58            }
     59            double result = expr.getResult();
     60        }
     61        else
     62            COUT(1) << "Error: Cannot calculate expression: Parse error." << std::endl;
     63        @endcode
     64        getRemains() returns the expression after what could be parsed. For instance
     65        \c "2*3 text" will return \c "text" as remains.
     66    @details
     67        The implementation of this class is really old and sort of a trial for
     68        a first C++ class by Reto. That explains why it looks more like C than
     69        C++... Also some of the variable names are in German. <br>
     70        Explaining how it works exactly is probably not possible anymore, but it
     71        is based on recursively parsing the expression character by character.
     72        That much I can remember.
     73    @par Functions, operators and variables supported
     74        - Variables:
     75            - e
     76            - pi
     77        - Functions:
     78            - sin, asin, sinh, asinh
     79            - cos, acos, cosh, acosh
     80            - tan, atan, tanh, atanh
     81            - int, floor, ceil, abs, sign
     82            - pow, sqrt, exp, ln, log
     83            - mod, div
     84            - min, max
     85            - radians, degrees
     86        - Operators:
     87            - +, -, ! (unary)
     88            - +, -, *, /, %, ^, |, &, !, <, >, !=, <=, >=, =
     89    @note
     90        Operators may not be very consistent with C++ rules, but using the class
     91        for plus and minus should be perfectly ok.
     92    */
    4493    class _UtilExport ExprParser
    4594    {

  • code/trunk/src/libraries/util/ImplicitConversion.h

    r7305 r7401  
    2929/**
    3030    @file
     31    @ingroup Util
    3132    @brief Declaration of various helper templates.
    3233*/

  • code/trunk/src/libraries/util/Math.cc

    r7284 r7401  
    9191        @param mydirection My viewing direction
    9292        @param otherposition The position of the other object
    93         @return The angle
    94 
    95         @example
    96         If the other object is exactly in front of me, the function returns 0.
    97         If the other object is exactly behind me, the function returns pi.
    98         If the other object is exactly right/left to me (or above/below), the function returns pi/2.
     93        @return The angle in radian
     94
     95        Examples:
     96         - If the other object is exactly in front of me, the function returns 0.
     97         - If the other object is exactly behind me, the function returns pi.
     98         - If the other object is exactly right/left to me (or above/below), the function returns pi/2.
    9999    */
    100100    float getAngle(const orxonox::Vector3& myposition, const orxonox::Vector3& mydirection, const orxonox::Vector3& otherposition)
    … …  
    116116        @return The viewing direction
    117117
    118         @example
    119         If the other object is exactly in front of me, the function returns Vector2(0, 0).
    120         If the other object is exactly at my left, the function returns Vector2(-1, 0).
    121         If the other object is exactly at my right, the function returns Vector2(1, 0).
    122         If the other object is only a bit at my right, the function still returns Vector2(1, 0).
    123         If the other object is exactly above me, the function returns Vector2(0, 1).
     118        Examples:
     119         - If the other object is exactly in front of me, the function returns <tt>Vector2(0, 0)</tt>.
     120         - If the other object is exactly at my left, the function returns <tt>Vector2(-1, 0)</tt>.
     121         - If the other object is exactly at my right, the function returns <tt>Vector2(1, 0)</tt>.
     122         - If the other object is only a bit at my right, the function still returns <tt>Vector2(1, 0)</tt>.
     123         - If the other object is exactly above me, the function returns <tt>Vector2(0, 1)</tt>.
    124124    */
    125125    orxonox::Vector2 get2DViewdirection(const orxonox::Vector3& myposition, const orxonox::Vector3& mydirection, const orxonox::Vector3& myorthonormal, const orxonox::Vector3& otherposition)
    … …  
    156156        @return The viewing direction
    157157
    158         @example
    159         If the other object is exactly in front of me, the function returns Vector2(0, 0).
    160         If the other object is exactly at my left, the function returns Vector2(-0.5, 0).
    161         If the other object is exactly at my right, the function returns Vector2(0.5, 0).
    162         If the other object is only a bit at my right, the function still returns Vector2(0.01, 0).
    163         If the other object is exactly above me, the function returns Vector2(0, 0.5).
     158        Examples:
     159         - If the other object is exactly in front of me, the function returns <tt>Vector2(0, 0)</tt>.
     160         - If the other object is exactly at my left, the function returns <tt>Vector2(-0.5, 0)</tt>.
     161         - If the other object is exactly at my right, the function returns <tt>Vector2(0.5, 0)</tt>.
     162         - If the other object is only a bit at my right, the function still returns <tt>Vector2(0.01, 0)</tt>.
     163         - If the other object is exactly above me, the function returns <tt>Vector2(0, 0.5)</tt>.
    164164    */
    165165    orxonox::Vector2 get2DViewcoordinates(const orxonox::Vector3& myposition, const orxonox::Vector3& mydirection, const orxonox::Vector3& myorthonormal, const orxonox::Vector3& otherposition)
    … …  
    220220    }
    221221
     222    /**
     223        @brief Returns a unique number. This function will never return the same value twice.
     224    */
    222225    unsigned long getUniqueNumber()
    223226    {

  • code/trunk/src/libraries/util/Math.h

    r7184 r7401  
    2828
    2929/**
     30    @defgroup Math Mathematical functions
     31    @ingroup Util
     32*/
     33
     34/**
    3035    @file
     36    @ingroup Math
    3137    @brief Declaration and implementation of several math-functions, typedefs of some Ogre::Math classes to the orxonox namespace.
    3238*/
    … …  
    6268    namespace math
    6369    {
    64         const float pi      = 3.14159265f;
    65         const float pi_2    = 1.57079633f;
    66         const float pi_4    = 7.85398163e-1f;
    67         const float e       = 2.71828183f;
    68         const float sqrt2   = 1.41421356f;
    69         const float sqrt2_2 = 7.07106781e-1f;
    70 
    71         const double pi_d      = 3.14159265358979324;
    72         const double pi_2_d    = 1.57079632679489662;
    73         const double pi_4_d    = 7.85398163397448310e-1;
    74         const double e_d       = 2.71828182845904524;
    75         const double sqrt2_d   = 1.41421356237309505;
    76         const double sqrt2_2_d = 7.07106781186547524e-1;
     70        const float pi      = 3.14159265f;      ///< PI
     71        const float pi_2    = 1.57079633f;      ///< PI / 2
     72        const float pi_4    = 7.85398163e-1f;   ///< PI / 4
     73        const float e       = 2.71828183f;      ///< e
     74        const float sqrt2   = 1.41421356f;      ///< sqrt(2)
     75        const float sqrt2_2 = 7.07106781e-1f;   ///< sqrt(2) / 2
     76
     77        const double pi_d      = 3.14159265358979324;       ///< PI (double)
     78        const double pi_2_d    = 1.57079632679489662;       ///< PI / 2 (double)
     79        const double pi_4_d    = 7.85398163397448310e-1;    ///< PI / 4 (double)
     80        const double e_d       = 2.71828182845904524;       ///< e (double)
     81        const double sqrt2_d   = 1.41421356237309505;       ///< sqrt(2) (double)
     82        const double sqrt2_2_d = 7.07106781186547524e-1;    ///< sqrt(2) / 2 (double)
    7783    }
    7884
    … …  
    101107
    102108    /**
    103         @brief Keeps a value between a lower and an upper limit.
     109        @brief Keeps a value between a lower and an upper limit. Values beyond these limits are limited to either @a min or @a max.
    104110        @param x The value
    105111        @param min The lower limit
    … …  
    119125
    120126    /**
    121         @brief Returns the square value (x^2).
     127        @brief Returns the squared value (x^2).
    122128    */
    123129    template <typename T>
    … …  
    128134
    129135    /**
    130         @brief Returns the cube value (x^3).
     136        @brief Returns the cubed value (x^3).
    131137    */
    132138    template <typename T>
    … …  
    137143
    138144    /**
    139         @brief Rounds the value.
     145        @brief Rounds the value to the nearest integer.
    140146    */
    141147    template <typename T>
    … …  
    149155        @param x The value
    150156        @param max The operand
     157
     158        The built in modulo operator % yields a strange behavior with negative values.
     159        This function corrects this - the result is guaranteed to lie always between
     160        zero and (max-1).
     161
     162        Example:
     163        @code
     164        int var = 11 % 10;      //  1
     165        int var = -1 % 10;      // -1
     166
     167        int var = mod(11, 10);  //  1
     168        int var = mod(-1, 10);  //  9
     169        @endcode
    151170    */
    152171    template <typename T>
    … …  
    159178    }
    160179
     180    /**
     181        @brief Returns a "zero" value for the given type.
     182        @note This is the default template of the zeroise() function. The template is spezialized for each supported type.
     183
     184        The exact return value of the function depends on the type. For @c int this is 0,
     185        for @c float it's 0.0f. For a @c std::string the function returns "" and for
     186        @c Vector3 you get <tt>Vector3(0, 0, 0)</tt>.
     187    */
    161188    template <typename T>
    162189    inline T zeroise()
    … …  
    192219    template <> inline orxonox::Quaternion  zeroise<orxonox::Quaternion>()  { return orxonox::Quaternion (0, 0, 0, 0); }
    193220
    194     //! Provides zero value symbols that can be returned as reference
     221    /**
     222        @brief Provides zero value symbols that can be returned as reference
     223        @see zeroise()
     224    */
    195225    template <typename T>
    196226    struct NilValue
    … …  
    207237    /**
    208238        @brief Interpolates between two values for a time between 0 and 1.
    209         @param time The time is a value between 0 and 1 - the function returns start if time is 0 and end if time is 1 and interpolates if time is between 0 and 1.
    210         @param start The value at time = 0
    211         @param end The value at time = 1
    212         @return The interpolation at a given time
     239        @param time The time is a value between 0 and 1 - the function returns @a start if @a time is 0, @a end if @a time is 1, and interpolates if @a time is between 0 and 1.
     240        @param start The value at @a time = 0
     241        @param end The value at @a time = 1
     242        @return The interpolated value at a given time
    213243    */
    214244    template <typename T>
    … …  
    220250    /**
    221251        @brief Interpolates smoothly between two values for a time between 0 and 1. The function starts slowly, increases faster and stops slowly again.
    222         @param time The time is a value between 0 and 1 - the function returns start if time is 0 and end if time is 1 and interpolates if time is between 0 and 1.
    223         @param start The value at time = 0
    224         @param end The value at time = 1
    225         @return The smoothed interpolation at a given time
     252        @param time The time is a value between 0 and 1 - the function returns @a start if @a time is 0, @a end if @a time is 1, and interpolates if @a time is between 0 and 1.
     253        @param start The value at @a time = 0
     254        @param end The value at @a time = 1
     255        @return The interpolated value at a given time
    226256    */
    227257    template <typename T>
    … …  
    232262
    233263    /**
    234         @brief Returns a random number between 0 and almost 1: 0 <= rnd < 1.
     264        @brief Returns a random number between 0 and almost 1: <tt>0 <= rnd < 1</tt>.
    235265    */
    236266    inline float rnd()
    … …  
    240270
    241271    /**
    242         @brief Returns a random number between 0 and almost max: 0 <= rnd < max.
     272        @brief Returns a random number between 0 and almost @a max: <tt>0 <= rnd < max</tt>.
    243273        @param max The maximum
    244274    */
    … …  
    249279
    250280    /**
    251         @brief Returns a random number between min and almost max: min <= rnd < max.
     281        @brief Returns a random number between @a min and almost @a max: <tt>min <= rnd < max</tt>.
    252282        @param min The minimum
    253283        @param max The maximum
    … …  
    268298    _UtilExport unsigned long getUniqueNumber();
    269299
     300    /**
     301        @brief A Vector class containing two integers @a x and @a y.
     302    */
    270303    class IntVector2
    271304    {
    … …  
    277310    };
    278311
     312    /**
     313        @brief A Vector class containing three integers @a x, @a y, and @a z.
     314    */
    279315    class IntVector3
    280316    {

  • code/trunk/src/libraries/util/MathConvert.h

    r6417 r7401  
    2828
    2929/**
    30     @file
    31     @brief
    32         Math conversion functions. Definitions are in Math.cc
     30@file
     31@ingroup Convert
     32@brief
     33    Conversion functions for Math types like Ogre::Vector3 (definitions are in Math.cc)
    3334*/
    3435
    … …  
    4647    ////////////////////
    4748
    48     // Vector2 to std::string
     49    /// Ogre::Vector2 to std::string conversion
    4950    template <>
    5051    struct ConverterExplicit<orxonox::Vector2, std::string>
    … …  
    6263    };
    6364
    64     // Vector3 to std::string
     65    /// Ogre::Vector3 to std::string conversion
    6566    template <>
    6667    struct ConverterExplicit<orxonox::Vector3, std::string>
    … …  
    7879    };
    7980
    80     // Vector4 to std::string
     81    /// Ogre::Vector4 to std::string conversion
    8182    template <>
    8283    struct ConverterExplicit<orxonox::Vector4, std::string>
    … …  
    9495    };
    9596
    96     // Quaternion to std::string
     97    /// Ogre::Quaternion to std::string conversion
    9798    template <>
    9899    struct ConverterExplicit<orxonox::Quaternion, std::string>
    … …  
    110111    };
    111112
    112     // ColourValue to std::string
     113    /// Ogre::ColourValue to std::string conversion
    113114    template <>
    114115    struct ConverterExplicit<orxonox::ColourValue, std::string>
    … …  
    131132    ////////////////////
    132133
    133     // std::string to Vector2
     134    /// std::string to Ogre::Vector2 conversion
    134135    template <> struct _UtilExport ConverterFallback<std::string, orxonox::Vector2>
    135136    { static bool convert(orxonox::Vector2*     output, const std::string& input); };
    136     // std::string to Vector3
     137    /// std::string to Ogre::Vector3 conversion
    137138    template <> struct _UtilExport ConverterFallback<std::string, orxonox::Vector3>
    138139    { static bool convert(orxonox::Vector3*     output, const std::string& input); };
    139     // std::string to Vector4
     140    /// std::string to Ogre::Vector4 conversion
    140141    template <> struct _UtilExport ConverterFallback<std::string, orxonox::Vector4>
    141142    { static bool convert(orxonox::Vector4*     output, const std::string& input); };
    142     // std::string to Quaternion
     143    /// std::string to Ogre::Quaternion conversion
    143144    template <> struct _UtilExport ConverterFallback<std::string, orxonox::Quaternion>
    144145    { static bool convert(orxonox::Quaternion*  output, const std::string& input); };
    145     // std::string to ColourValue
     146    /// std::string to Ogre::ColourValue conversion
    146147    template <> struct _UtilExport ConverterFallback<std::string, orxonox::ColourValue>
    147148    { static bool convert(orxonox::ColourValue* output, const std::string& input); };
    … …  
    152153    ///////////////////////////////
    153154
    154     // From Radian
     155    /// Delegates conversions from Radian to conversions from float
    155156    template <class ToType>
    156157    struct ConverterFallback<orxonox::Radian, ToType>
    … …  
    162163    };
    163164
    164     // From Degree
     165    /// Delegates conversions from Degree to conversions from float
    165166    template <class ToType>
    166167    struct ConverterFallback<orxonox::Degree, ToType>
    … …  
    172173    };
    173174
    174     // To Radian
     175    /// Delegates conversions to Radian to conversions to float
    175176    template <class FromType>
    176177    struct ConverterFallback<FromType, orxonox::Radian>
    … …  
    189190    };
    190191
    191     // To Degree
     192    /// Delegates conversions to Degree to conversions to float
    192193    template <class FromType>
    193194    struct ConverterFallback<FromType, orxonox::Degree>

  • code/trunk/src/libraries/util/MultiType.cc

    r5738 r7401  
    159159    }
    160160
    161     MultiType::operator char()                 const { return (this->value_) ? ((this->value_->type_ == MT_Type::Char            ) ? (static_cast<MT_Value<char>                *>(this->value_))->value_ : (*this->value_)) : 0;                      } /** @brief Returns the current value, converted to the requested type. */
    162     MultiType::operator unsigned char()        const { return (this->value_) ? ((this->value_->type_ == MT_Type::UnsignedChar    ) ? (static_cast<MT_Value<unsigned char>       *>(this->value_))->value_ : (*this->value_)) : 0;                      } /** @brief Returns the current value, converted to the requested type. */
    163     MultiType::operator short()                const { return (this->value_) ? ((this->value_->type_ == MT_Type::Short           ) ? (static_cast<MT_Value<short>               *>(this->value_))->value_ : (*this->value_)) : 0;                      } /** @brief Returns the current value, converted to the requested type. */
    164     MultiType::operator unsigned short()       const { return (this->value_) ? ((this->value_->type_ == MT_Type::UnsignedShort   ) ? (static_cast<MT_Value<unsigned short>      *>(this->value_))->value_ : (*this->value_)) : 0;                      } /** @brief Returns the current value, converted to the requested type. */
    165     MultiType::operator int()                  const { return (this->value_) ? ((this->value_->type_ == MT_Type::Int             ) ? (static_cast<MT_Value<int>                 *>(this->value_))->value_ : (*this->value_)) : 0;                      } /** @brief Returns the current value, converted to the requested type. */
    166     MultiType::operator unsigned int()         const { return (this->value_) ? ((this->value_->type_ == MT_Type::UnsignedInt     ) ? (static_cast<MT_Value<unsigned int>        *>(this->value_))->value_ : (*this->value_)) : 0;                      } /** @brief Returns the current value, converted to the requested type. */
    167     MultiType::operator long()                 const { return (this->value_) ? ((this->value_->type_ == MT_Type::Long            ) ? (static_cast<MT_Value<long>                *>(this->value_))->value_ : (*this->value_)) : 0;                      } /** @brief Returns the current value, converted to the requested type. */
    168     MultiType::operator unsigned long()        const { return (this->value_) ? ((this->value_->type_ == MT_Type::UnsignedLong    ) ? (static_cast<MT_Value<unsigned long>       *>(this->value_))->value_ : (*this->value_)) : 0;                      } /** @brief Returns the current value, converted to the requested type. */
    169     MultiType::operator long long()            const { return (this->value_) ? ((this->value_->type_ == MT_Type::LongLong        ) ? (static_cast<MT_Value<long long>           *>(this->value_))->value_ : (*this->value_)) : 0;                      } /** @brief Returns the current value, converted to the requested type. */
    170     MultiType::operator unsigned long long()   const { return (this->value_) ? ((this->value_->type_ == MT_Type::UnsignedLongLong) ? (static_cast<MT_Value<unsigned long long>  *>(this->value_))->value_ : (*this->value_)) : 0;                      } /** @brief Returns the current value, converted to the requested type. */
    171     MultiType::operator float()                const { return (this->value_) ? ((this->value_->type_ == MT_Type::Float           ) ? (static_cast<MT_Value<float>               *>(this->value_))->value_ : (*this->value_)) : 0;                      } /** @brief Returns the current value, converted to the requested type. */
    172     MultiType::operator double()               const { return (this->value_) ? ((this->value_->type_ == MT_Type::Double          ) ? (static_cast<MT_Value<double>              *>(this->value_))->value_ : (*this->value_)) : 0;                      } /** @brief Returns the current value, converted to the requested type. */
    173     MultiType::operator long double()          const { return (this->value_) ? ((this->value_->type_ == MT_Type::LongDouble      ) ? (static_cast<MT_Value<long double>         *>(this->value_))->value_ : (*this->value_)) : 0;                      } /** @brief Returns the current value, converted to the requested type. */
    174     MultiType::operator bool()                 const { return (this->value_) ? ((this->value_->type_ == MT_Type::Bool            ) ? (static_cast<MT_Value<bool>                *>(this->value_))->value_ : (*this->value_)) : 0;                      } /** @brief Returns the current value, converted to the requested type. */
    175     MultiType::operator void*()                const { return (this->value_) ? ((this->value_->type_ == MT_Type::VoidPointer     ) ? (static_cast<MT_Value<void*>               *>(this->value_))->value_ : (*this->value_)) : 0;                      } /** @brief Returns the current value, converted to the requested type. */
    176     MultiType::operator std::string()          const { return (this->value_) ? ((this->value_->type_ == MT_Type::String          ) ? (static_cast<MT_Value<std::string>         *>(this->value_))->value_ : (*this->value_)) : NilValue<std::string>();          } /** @brief Returns the current value, converted to the requested type. */
    177     MultiType::operator orxonox::Vector2()     const { return (this->value_) ? ((this->value_->type_ == MT_Type::Vector2         ) ? (static_cast<MT_Value<orxonox::Vector2>    *>(this->value_))->value_ : (*this->value_)) : NilValue<orxonox::Vector2>();     } /** @brief Returns the current value, converted to the requested type. */
    178     MultiType::operator orxonox::Vector3()     const { return (this->value_) ? ((this->value_->type_ == MT_Type::Vector3         ) ? (static_cast<MT_Value<orxonox::Vector3>    *>(this->value_))->value_ : (*this->value_)) : NilValue<orxonox::Vector3>();     } /** @brief Returns the current value, converted to the requested type. */
    179     MultiType::operator orxonox::Vector4()     const { return (this->value_) ? ((this->value_->type_ == MT_Type::Vector4         ) ? (static_cast<MT_Value<orxonox::Vector4>    *>(this->value_))->value_ : (*this->value_)) : NilValue<orxonox::Vector4>();     } /** @brief Returns the current value, converted to the requested type. */
    180     MultiType::operator orxonox::ColourValue() const { return (this->value_) ? ((this->value_->type_ == MT_Type::ColourValue     ) ? (static_cast<MT_Value<orxonox::ColourValue>*>(this->value_))->value_ : (*this->value_)) : NilValue<orxonox::ColourValue>(); } /** @brief Returns the current value, converted to the requested type. */
    181     MultiType::operator orxonox::Quaternion()  const { return (this->value_) ? ((this->value_->type_ == MT_Type::Quaternion      ) ? (static_cast<MT_Value<orxonox::Quaternion> *>(this->value_))->value_ : (*this->value_)) : NilValue<orxonox::Quaternion>();  } /** @brief Returns the current value, converted to the requested type. */
    182     MultiType::operator orxonox::Radian()      const { return (this->value_) ? ((this->value_->type_ == MT_Type::Radian          ) ? (static_cast<MT_Value<orxonox::Radian>     *>(this->value_))->value_ : (*this->value_)) : NilValue<orxonox::Radian>();      } /** @brief Returns the current value, converted to the requested type. */
    183     MultiType::operator orxonox::Degree()      const { return (this->value_) ? ((this->value_->type_ == MT_Type::Degree          ) ? (static_cast<MT_Value<orxonox::Degree>     *>(this->value_))->value_ : (*this->value_)) : NilValue<orxonox::Degree>();      } /** @brief Returns the current value, converted to the requested type. */
    184 
    185     template <> void MultiType::createNewValueContainer(const char& value)                 { this->value_ = new MT_Value<char>                (value, MT_Type::Char            ); } /** @brief Creates a new value container for the given type. */
    186     template <> void MultiType::createNewValueContainer(const unsigned char& value)        { this->value_ = new MT_Value<unsigned char>       (value, MT_Type::UnsignedChar    ); } /** @brief Creates a new value container for the given type. */
    187     template <> void MultiType::createNewValueContainer(const short& value)                { this->value_ = new MT_Value<short>               (value, MT_Type::Short           ); } /** @brief Creates a new value container for the given type. */
    188     template <> void MultiType::createNewValueContainer(const unsigned short& value)       { this->value_ = new MT_Value<unsigned short>      (value, MT_Type::UnsignedShort   ); } /** @brief Creates a new value container for the given type. */
    189     template <> void MultiType::createNewValueContainer(const int& value)                  { this->value_ = new MT_Value<int>                 (value, MT_Type::Int             ); } /** @brief Creates a new value container for the given type. */
    190     template <> void MultiType::createNewValueContainer(const unsigned int& value)         { this->value_ = new MT_Value<unsigned int>        (value, MT_Type::UnsignedInt     ); } /** @brief Creates a new value container for the given type. */
    191     template <> void MultiType::createNewValueContainer(const long& value)                 { this->value_ = new MT_Value<long>                (value, MT_Type::Long            ); } /** @brief Creates a new value container for the given type. */
    192     template <> void MultiType::createNewValueContainer(const unsigned long& value)        { this->value_ = new MT_Value<unsigned long>       (value, MT_Type::UnsignedLong    ); } /** @brief Creates a new value container for the given type. */
    193     template <> void MultiType::createNewValueContainer(const long long& value)            { this->value_ = new MT_Value<long long>           (value, MT_Type::LongLong        ); } /** @brief Creates a new value container for the given type. */
    194     template <> void MultiType::createNewValueContainer(const unsigned long long& value)   { this->value_ = new MT_Value<unsigned long long>  (value, MT_Type::UnsignedLongLong); } /** @brief Creates a new value container for the given type. */
    195     template <> void MultiType::createNewValueContainer(const float& value)                { this->value_ = new MT_Value<float>               (value, MT_Type::Float           ); } /** @brief Creates a new value container for the given type. */
    196     template <> void MultiType::createNewValueContainer(const double& value)               { this->value_ = new MT_Value<double>              (value, MT_Type::Double          ); } /** @brief Creates a new value container for the given type. */
    197     template <> void MultiType::createNewValueContainer(const long double& value)          { this->value_ = new MT_Value<long double>         (value, MT_Type::LongDouble      ); } /** @brief Creates a new value container for the given type. */
    198     template <> void MultiType::createNewValueContainer(const bool& value)                 { this->value_ = new MT_Value<bool>                (value, MT_Type::Bool            ); } /** @brief Creates a new value container for the given type. */
    199     template <> void MultiType::createNewValueContainer(      void* const& value)          { this->value_ = new MT_Value<void*>               (value, MT_Type::VoidPointer     ); } /** @brief Creates a new value container for the given type. */
    200     template <> void MultiType::createNewValueContainer(const std::string& value)          { this->value_ = new MT_Value<std::string>         (value, MT_Type::String          ); } /** @brief Creates a new value container for the given type. */
    201     template <> void MultiType::createNewValueContainer(const orxonox::Vector2& value)     { this->value_ = new MT_Value<orxonox::Vector2>    (value, MT_Type::Vector2         ); } /** @brief Creates a new value container for the given type. */
    202     template <> void MultiType::createNewValueContainer(const orxonox::Vector3& value)     { this->value_ = new MT_Value<orxonox::Vector3>    (value, MT_Type::Vector3         ); } /** @brief Creates a new value container for the given type. */
    203     template <> void MultiType::createNewValueContainer(const orxonox::Vector4& value)     { this->value_ = new MT_Value<orxonox::Vector4>    (value, MT_Type::Vector4         ); } /** @brief Creates a new value container for the given type. */
    204     template <> void MultiType::createNewValueContainer(const orxonox::ColourValue& value) { this->value_ = new MT_Value<orxonox::ColourValue>(value, MT_Type::ColourValue     ); } /** @brief Creates a new value container for the given type. */
    205     template <> void MultiType::createNewValueContainer(const orxonox::Quaternion& value)  { this->value_ = new MT_Value<orxonox::Quaternion> (value, MT_Type::Quaternion      ); } /** @brief Creates a new value container for the given type. */
    206     template <> void MultiType::createNewValueContainer(const orxonox::Radian& value)      { this->value_ = new MT_Value<orxonox::Radian>     (value, MT_Type::Radian          ); } /** @brief Creates a new value container for the given type. */
    207     template <> void MultiType::createNewValueContainer(const orxonox::Degree& value)      { this->value_ = new MT_Value<orxonox::Degree>     (value, MT_Type::Degree          ); } /** @brief Creates a new value container for the given type. */
     161    MultiType::operator char()                 const { return (this->value_) ? ((this->value_->type_ == MT_Type::Char            ) ? (static_cast<MT_Value<char>                *>(this->value_))->value_ : (*this->value_)) : 0;                      } ///< Returns the current value, converted to the requested type.
     162    MultiType::operator unsigned char()        const { return (this->value_) ? ((this->value_->type_ == MT_Type::UnsignedChar    ) ? (static_cast<MT_Value<unsigned char>       *>(this->value_))->value_ : (*this->value_)) : 0;                      } ///< Returns the current value, converted to the requested type.
     163    MultiType::operator short()                const { return (this->value_) ? ((this->value_->type_ == MT_Type::Short           ) ? (static_cast<MT_Value<short>               *>(this->value_))->value_ : (*this->value_)) : 0;                      } ///< Returns the current value, converted to the requested type.
     164    MultiType::operator unsigned short()       const { return (this->value_) ? ((this->value_->type_ == MT_Type::UnsignedShort   ) ? (static_cast<MT_Value<unsigned short>      *>(this->value_))->value_ : (*this->value_)) : 0;                      } ///< Returns the current value, converted to the requested type.
     165    MultiType::operator int()                  const { return (this->value_) ? ((this->value_->type_ == MT_Type::Int             ) ? (static_cast<MT_Value<int>                 *>(this->value_))->value_ : (*this->value_)) : 0;                      } ///< Returns the current value, converted to the requested type.
     166    MultiType::operator unsigned int()         const { return (this->value_) ? ((this->value_->type_ == MT_Type::UnsignedInt     ) ? (static_cast<MT_Value<unsigned int>        *>(this->value_))->value_ : (*this->value_)) : 0;                      } ///< Returns the current value, converted to the requested type.
     167    MultiType::operator long()                 const { return (this->value_) ? ((this->value_->type_ == MT_Type::Long            ) ? (static_cast<MT_Value<long>                *>(this->value_))->value_ : (*this->value_)) : 0;                      } ///< Returns the current value, converted to the requested type.
     168    MultiType::operator unsigned long()        const { return (this->value_) ? ((this->value_->type_ == MT_Type::UnsignedLong    ) ? (static_cast<MT_Value<unsigned long>       *>(this->value_))->value_ : (*this->value_)) : 0;                      } ///< Returns the current value, converted to the requested type.
     169    MultiType::operator long long()            const { return (this->value_) ? ((this->value_->type_ == MT_Type::LongLong        ) ? (static_cast<MT_Value<long long>           *>(this->value_))->value_ : (*this->value_)) : 0;                      } ///< Returns the current value, converted to the requested type.
     170    MultiType::operator unsigned long long()   const { return (this->value_) ? ((this->value_->type_ == MT_Type::UnsignedLongLong) ? (static_cast<MT_Value<unsigned long long>  *>(this->value_))->value_ : (*this->value_)) : 0;                      } ///< Returns the current value, converted to the requested type.
     171    MultiType::operator float()                const { return (this->value_) ? ((this->value_->type_ == MT_Type::Float           ) ? (static_cast<MT_Value<float>               *>(this->value_))->value_ : (*this->value_)) : 0;                      } ///< Returns the current value, converted to the requested type.
     172    MultiType::operator double()               const { return (this->value_) ? ((this->value_->type_ == MT_Type::Double          ) ? (static_cast<MT_Value<double>              *>(this->value_))->value_ : (*this->value_)) : 0;                      } ///< Returns the current value, converted to the requested type.
     173    MultiType::operator long double()          const { return (this->value_) ? ((this->value_->type_ == MT_Type::LongDouble      ) ? (static_cast<MT_Value<long double>         *>(this->value_))->value_ : (*this->value_)) : 0;                      } ///< Returns the current value, converted to the requested type.
     174    MultiType::operator bool()                 const { return (this->value_) ? ((this->value_->type_ == MT_Type::Bool            ) ? (static_cast<MT_Value<bool>                *>(this->value_))->value_ : (*this->value_)) : 0;                      } ///< Returns the current value, converted to the requested type.
     175    MultiType::operator void*()                const { return (this->value_) ? ((this->value_->type_ == MT_Type::VoidPointer     ) ? (static_cast<MT_Value<void*>               *>(this->value_))->value_ : (*this->value_)) : 0;                      } ///< Returns the current value, converted to the requested type.
     176    MultiType::operator std::string()          const { return (this->value_) ? ((this->value_->type_ == MT_Type::String          ) ? (static_cast<MT_Value<std::string>         *>(this->value_))->value_ : (*this->value_)) : NilValue<std::string>();          } ///< Returns the current value, converted to the requested type.
     177    MultiType::operator orxonox::Vector2()     const { return (this->value_) ? ((this->value_->type_ == MT_Type::Vector2         ) ? (static_cast<MT_Value<orxonox::Vector2>    *>(this->value_))->value_ : (*this->value_)) : NilValue<orxonox::Vector2>();     } ///< Returns the current value, converted to the requested type.
     178    MultiType::operator orxonox::Vector3()     const { return (this->value_) ? ((this->value_->type_ == MT_Type::Vector3         ) ? (static_cast<MT_Value<orxonox::Vector3>    *>(this->value_))->value_ : (*this->value_)) : NilValue<orxonox::Vector3>();     } ///< Returns the current value, converted to the requested type.
     179    MultiType::operator orxonox::Vector4()     const { return (this->value_) ? ((this->value_->type_ == MT_Type::Vector4         ) ? (static_cast<MT_Value<orxonox::Vector4>    *>(this->value_))->value_ : (*this->value_)) : NilValue<orxonox::Vector4>();     } ///< Returns the current value, converted to the requested type.
     180    MultiType::operator orxonox::ColourValue() const { return (this->value_) ? ((this->value_->type_ == MT_Type::ColourValue     ) ? (static_cast<MT_Value<orxonox::ColourValue>*>(this->value_))->value_ : (*this->value_)) : NilValue<orxonox::ColourValue>(); } ///< Returns the current value, converted to the requested type.
     181    MultiType::operator orxonox::Quaternion()  const { return (this->value_) ? ((this->value_->type_ == MT_Type::Quaternion      ) ? (static_cast<MT_Value<orxonox::Quaternion> *>(this->value_))->value_ : (*this->value_)) : NilValue<orxonox::Quaternion>();  } ///< Returns the current value, converted to the requested type.
     182    MultiType::operator orxonox::Radian()      const { return (this->value_) ? ((this->value_->type_ == MT_Type::Radian          ) ? (static_cast<MT_Value<orxonox::Radian>     *>(this->value_))->value_ : (*this->value_)) : NilValue<orxonox::Radian>();      } ///< Returns the current value, converted to the requested type.
     183    MultiType::operator orxonox::Degree()      const { return (this->value_) ? ((this->value_->type_ == MT_Type::Degree          ) ? (static_cast<MT_Value<orxonox::Degree>     *>(this->value_))->value_ : (*this->value_)) : NilValue<orxonox::Degree>();      } ///< Returns the current value, converted to the requested type.
     184
     185    template <> void MultiType::createNewValueContainer(const char& value)                 { this->value_ = new MT_Value<char>                (value, MT_Type::Char            ); } ///< Creates a new value container for the given type.
     186    template <> void MultiType::createNewValueContainer(const unsigned char& value)        { this->value_ = new MT_Value<unsigned char>       (value, MT_Type::UnsignedChar    ); } ///< Creates a new value container for the given type.
     187    template <> void MultiType::createNewValueContainer(const short& value)                { this->value_ = new MT_Value<short>               (value, MT_Type::Short           ); } ///< Creates a new value container for the given type.
     188    template <> void MultiType::createNewValueContainer(const unsigned short& value)       { this->value_ = new MT_Value<unsigned short>      (value, MT_Type::UnsignedShort   ); } ///< Creates a new value container for the given type.
     189    template <> void MultiType::createNewValueContainer(const int& value)                  { this->value_ = new MT_Value<int>                 (value, MT_Type::Int             ); } ///< Creates a new value container for the given type.
     190    template <> void MultiType::createNewValueContainer(const unsigned int& value)         { this->value_ = new MT_Value<unsigned int>        (value, MT_Type::UnsignedInt     ); } ///< Creates a new value container for the given type.
     191    template <> void MultiType::createNewValueContainer(const long& value)                 { this->value_ = new MT_Value<long>                (value, MT_Type::Long            ); } ///< Creates a new value container for the given type.
     192    template <> void MultiType::createNewValueContainer(const unsigned long& value)        { this->value_ = new MT_Value<unsigned long>       (value, MT_Type::UnsignedLong    ); } ///< Creates a new value container for the given type.
     193    template <> void MultiType::createNewValueContainer(const long long& value)            { this->value_ = new MT_Value<long long>           (value, MT_Type::LongLong        ); } ///< Creates a new value container for the given type.
     194    template <> void MultiType::createNewValueContainer(const unsigned long long& value)   { this->value_ = new MT_Value<unsigned long long>  (value, MT_Type::UnsignedLongLong); } ///< Creates a new value container for the given type.
     195    template <> void MultiType::createNewValueContainer(const float& value)                { this->value_ = new MT_Value<float>               (value, MT_Type::Float           ); } ///< Creates a new value container for the given type.
     196    template <> void MultiType::createNewValueContainer(const double& value)               { this->value_ = new MT_Value<double>              (value, MT_Type::Double          ); } ///< Creates a new value container for the given type.
     197    template <> void MultiType::createNewValueContainer(const long double& value)          { this->value_ = new MT_Value<long double>         (value, MT_Type::LongDouble      ); } ///< Creates a new value container for the given type.
     198    template <> void MultiType::createNewValueContainer(const bool& value)                 { this->value_ = new MT_Value<bool>                (value, MT_Type::Bool            ); } ///< Creates a new value container for the given type.
     199    template <> void MultiType::createNewValueContainer(      void* const& value)          { this->value_ = new MT_Value<void*>               (value, MT_Type::VoidPointer     ); } ///< Creates a new value container for the given type.
     200    template <> void MultiType::createNewValueContainer(const std::string& value)          { this->value_ = new MT_Value<std::string>         (value, MT_Type::String          ); } ///< Creates a new value container for the given type.
     201    template <> void MultiType::createNewValueContainer(const orxonox::Vector2& value)     { this->value_ = new MT_Value<orxonox::Vector2>    (value, MT_Type::Vector2         ); } ///< Creates a new value container for the given type.
     202    template <> void MultiType::createNewValueContainer(const orxonox::Vector3& value)     { this->value_ = new MT_Value<orxonox::Vector3>    (value, MT_Type::Vector3         ); } ///< Creates a new value container for the given type.
     203    template <> void MultiType::createNewValueContainer(const orxonox::Vector4& value)     { this->value_ = new MT_Value<orxonox::Vector4>    (value, MT_Type::Vector4         ); } ///< Creates a new value container for the given type.
     204    template <> void MultiType::createNewValueContainer(const orxonox::ColourValue& value) { this->value_ = new MT_Value<orxonox::ColourValue>(value, MT_Type::ColourValue     ); } ///< Creates a new value container for the given type.
     205    template <> void MultiType::createNewValueContainer(const orxonox::Quaternion& value)  { this->value_ = new MT_Value<orxonox::Quaternion> (value, MT_Type::Quaternion      ); } ///< Creates a new value container for the given type.
     206    template <> void MultiType::createNewValueContainer(const orxonox::Radian& value)      { this->value_ = new MT_Value<orxonox::Radian>     (value, MT_Type::Radian          ); } ///< Creates a new value container for the given type.
     207    template <> void MultiType::createNewValueContainer(const orxonox::Degree& value)      { this->value_ = new MT_Value<orxonox::Degree>     (value, MT_Type::Degree          ); } ///< Creates a new value container for the given type.
    208208}

  • code/trunk/src/libraries/util/MultiType.h

    r7284 r7401  
    2828
    2929/**
     30    @defgroup MultiType MultiType
     31    @ingroup Util
     32*/
     33
     34/**
    3035    @file
     36    @ingroup MultiType
    3137    @brief Declaration of the MultiType and some helper constructs.
    3238
     39    @anchor MultiTypeExamples
     40
    3341    The MultiType can hold a value of one of the following types:
    34      - all primitives
    35      - all pointers
    36      - string
     42     - all primitives (int, float, bool, etc.)
     43     - all pointers (void* and T*)
     44     - std::string
    3745     - Vector2, Vector3, Vector4
    3846     - Quaternion
    … …  
    4048     - Radian, Degree
    4149
    42     The MultiType has a "type" determined by the first assigned value, either through
    43      - the constructor,
    44      - the assignment operator= or
    45      - setValue(value).
    46     If you assign another value of another type, the MultiType keeps "it's" type and
    47     converts the new value to this type.
     50    The MultiType has an internal "type" determined by the first assigned value, using one of these ways:
     51     - @ref orxonox::MultiType::MultiType "The constructor"
     52     - The assignment operator= (orxonox::MultiType::operator=())
     53     - @ref orxonox::MultiType::setValue() "setValue(value)"
     54
     55    If you assign another value of another type, the MultiType keeps "its" type and
     56    converts the new value to the old type.
    4857
    4958    If you want to change the type, there are three possibilities:
    50      - convert<T>() set's the type to T and converts the currently assigned value
    51      - setType<T>() set's the type to T and resets the value
     59     - @ref orxonox::MultiType::convert "convert<T>()" sets the type to T and converts the currently assigned value
     60     - @ref orxonox::MultiType::setType "setType<T>()" sets the type to T and resets the value to zero using zeroise<T>()
    5261     - setValue<T>(value) assigns a new value and changes the type to T.
    5362
    54     @example
    55     MultiType a = 10;;         // a has now the type int and the value 10
     63    Examples:
     64    @code
     65    MultiType a = 10;          // a has now the type int and the value 10
    5666    a.setValue("3.14");        // a has still the type int and "3.14" gets converted, therefore the value is now 3
    57     a.setValue<float>("3.14"); // a has now the type float and "3.14" gets converted to 3.14
    58     a.convert<bool>();         // converts 3.14 to bool, which is true
     67    a.setValue<float>("3.14"); // a has now the type float and "3.14" gets converted to 3.14f
     68    a.convert<bool>();         // converts 3.14f to bool, which is true
    5969    a = false;                 // assigns false, this is equivalent to a.setValue(false)
     70    @endcode
     71
     72    You can pass a MultiType to a function as an argument, even if the argument is
     73    not of type MultiType. This works, because the MultiType is automatically converted
     74    to the right type.
     75
     76    Example:
     77    @code
     78    void myfunction(int value)
     79    {
     80        COUT(0) << "doubled value is " << (2 * value) << std::endl;
     81    }
     82
     83    MultiType a = "50";        // Note: We assigned a string
     84    myfunction(a);             // a is converted to int and passed to the function, which prints "value is 100"
     85    @endcode
     86
     87    Note however that it is of course quite expensive to convert values, especially std::string <-> value.
     88    So if you can, always assign a value with the right type to avoid conversion.
    6089
    6190    @note
    … …  
    127156         - Radian, Degree
    128157
    129         The internal type of a MultiType is determined by the first assigned value, but can be
    130         changed by using setType<T>(), convert<T>() or setValue<T>(value). If a value gets assigned
    131         the normal way (operator=, setValue(value)), the value gets converted to the current internal
    132         type of the MultiType.
     158        For more information and some examples see the description @ref MultiTypeExamples "here".
     159
     160        @see MultiType.h
    133161    */
    134162    class _UtilExport MultiType
    … …  
    153181            virtual bool assimilate(const MultiType& other) = 0;
    154182
    155             /** @brief Returns the type of the current value. */
     183            /// Returns the type of the current value.
    156184            const MT_Type::Value& getType() const { return this->type_; }
    157185
    158             /** @brief Checks whether the value is a default one. */
     186            /// Checks whether the value is a default one.
    159187            bool hasDefaultValue()   const { return this->bHasDefaultValue_; }
    160188
    … …  
    237265            virtual uint8_t getSize() const=0;
    238266
    239             MT_Type::Value type_;   //!< The type of the current value
    240             bool bHasDefaultValue_; //!< True if the last conversion wasn't successful
     267            MT_Type::Value type_;   ///< The type of the current value
     268            bool bHasDefaultValue_; ///< True if the last conversion wasn't successful
    241269        };
    242270
    243271        public:
    244             inline MultiType()                                  : value_(0) {}                                      /** @brief Default constructor: Assigns no value and no type. The type will be determined by the first assignment of a value. */
    245             inline MultiType(const char& value)                 : value_(0) { this->assignValue(value); }           /** @brief Constructor: Assigns the given value and sets the type. */
    246             inline MultiType(const unsigned char& value)        : value_(0) { this->assignValue(value); }           /** @brief Constructor: Assigns the given value and sets the type. */
    247             inline MultiType(const short& value)                : value_(0) { this->assignValue(value); }           /** @brief Constructor: Assigns the given value and sets the type. */
    248             inline MultiType(const unsigned short& value)       : value_(0) { this->assignValue(value); }           /** @brief Constructor: Assigns the given value and sets the type. */
    249             inline MultiType(const int& value)                  : value_(0) { this->assignValue(value); }           /** @brief Constructor: Assigns the given value and sets the type. */
    250             inline MultiType(const unsigned int& value)         : value_(0) { this->assignValue(value); }           /** @brief Constructor: Assigns the given value and sets the type. */
    251             inline MultiType(const long& value)                 : value_(0) { this->assignValue(value); }           /** @brief Constructor: Assigns the given value and sets the type. */
    252             inline MultiType(const unsigned long& value)        : value_(0) { this->assignValue(value); }           /** @brief Constructor: Assigns the given value and sets the type. */
    253             inline MultiType(const long long& value)            : value_(0) { this->assignValue(value); }           /** @brief Constructor: Assigns the given value and sets the type. */
    254             inline MultiType(const unsigned long long& value)   : value_(0) { this->assignValue(value); }           /** @brief Constructor: Assigns the given value and sets the type. */
    255             inline MultiType(const float& value)                : value_(0) { this->assignValue(value); }           /** @brief Constructor: Assigns the given value and sets the type. */
    256             inline MultiType(const double& value)               : value_(0) { this->assignValue(value); }           /** @brief Constructor: Assigns the given value and sets the type. */
    257             inline MultiType(const long double& value)          : value_(0) { this->assignValue(value); }           /** @brief Constructor: Assigns the given value and sets the type. */
    258             inline MultiType(const bool& value)                 : value_(0) { this->assignValue(value); }           /** @brief Constructor: Assigns the given value and sets the type. */
    259             inline MultiType(      void* const& value)          : value_(0) { this->assignValue(value); }           /** @brief Constructor: Assigns the given value and sets the type. */
    260             inline MultiType(const std::string& value)          : value_(0) { this->assignValue(value); }           /** @brief Constructor: Assigns the given value and sets the type. */
    261             inline MultiType(const orxonox::Vector2& value)     : value_(0) { this->assignValue(value); }           /** @brief Constructor: Assigns the given value and sets the type. */
    262             inline MultiType(const orxonox::Vector3& value)     : value_(0) { this->assignValue(value); }           /** @brief Constructor: Assigns the given value and sets the type. */
    263             inline MultiType(const orxonox::Vector4& value)     : value_(0) { this->assignValue(value); }           /** @brief Constructor: Assigns the given value and sets the type. */
    264             inline MultiType(const orxonox::ColourValue& value) : value_(0) { this->assignValue(value); }           /** @brief Constructor: Assigns the given value and sets the type. */
    265             inline MultiType(const orxonox::Quaternion& value)  : value_(0) { this->assignValue(value); }           /** @brief Constructor: Assigns the given value and sets the type. */
    266             inline MultiType(const orxonox::Radian& value)      : value_(0) { this->assignValue(value); }           /** @brief Constructor: Assigns the given value and sets the type. */
    267             inline MultiType(const orxonox::Degree& value)      : value_(0) { this->assignValue(value); }           /** @brief Constructor: Assigns the given value and sets the type. */
    268             inline MultiType(const orxonox::mbool& value)       : value_(0) { this->assignValue((bool)value); }     /** @brief Constructor: Assigns the given mbool and converts it to bool. */
    269             inline MultiType(const char* value)                 : value_(0) { this->setValue(std::string(value)); } /** @brief Constructor: Converts the char array to a std::string, assigns the value and sets the type. */
    270             inline MultiType(const MultiType& other)            : value_(0) { this->setValue(other); }              /** @brief Copyconstructor: Assigns value and type of the other MultiType. */
    271             inline MultiType(MT_Type::Value type)               : value_(0) { this->setType(type); }                /** @brief Constructor: Sets the type, the next assignment will determine the value. */
    272 
    273             /** @brief Destructor: Deletes the MT_Value. */
     272            inline MultiType()                                  : value_(0) {}                                      ///< Default constructor: Assigns no value and no type. The type will be determined by the first assignment of a value.
     273            inline MultiType(const char& value)                 : value_(0) { this->assignValue(value); }           ///< Constructor: Assigns the given value and sets the type.
     274            inline MultiType(const unsigned char& value)        : value_(0) { this->assignValue(value); }           ///< Constructor: Assigns the given value and sets the type.
     275            inline MultiType(const short& value)                : value_(0) { this->assignValue(value); }           ///< Constructor: Assigns the given value and sets the type.
     276            inline MultiType(const unsigned short& value)       : value_(0) { this->assignValue(value); }           ///< Constructor: Assigns the given value and sets the type.
     277            inline MultiType(const int& value)                  : value_(0) { this->assignValue(value); }           ///< Constructor: Assigns the given value and sets the type.
     278            inline MultiType(const unsigned int& value)         : value_(0) { this->assignValue(value); }           ///< Constructor: Assigns the given value and sets the type.
     279            inline MultiType(const long& value)                 : value_(0) { this->assignValue(value); }           ///< Constructor: Assigns the given value and sets the type.
     280            inline MultiType(const unsigned long& value)        : value_(0) { this->assignValue(value); }           ///< Constructor: Assigns the given value and sets the type.
     281            inline MultiType(const long long& value)            : value_(0) { this->assignValue(value); }           ///< Constructor: Assigns the given value and sets the type.
     282            inline MultiType(const unsigned long long& value)   : value_(0) { this->assignValue(value); }           ///< Constructor: Assigns the given value and sets the type.
     283            inline MultiType(const float& value)                : value_(0) { this->assignValue(value); }           ///< Constructor: Assigns the given value and sets the type.
     284            inline MultiType(const double& value)               : value_(0) { this->assignValue(value); }           ///< Constructor: Assigns the given value and sets the type.
     285            inline MultiType(const long double& value)          : value_(0) { this->assignValue(value); }           ///< Constructor: Assigns the given value and sets the type.
     286            inline MultiType(const bool& value)                 : value_(0) { this->assignValue(value); }           ///< Constructor: Assigns the given value and sets the type.
     287            inline MultiType(      void* const& value)          : value_(0) { this->assignValue(value); }           ///< Constructor: Assigns the given value and sets the type.
     288            inline MultiType(const std::string& value)          : value_(0) { this->assignValue(value); }           ///< Constructor: Assigns the given value and sets the type.
     289            inline MultiType(const orxonox::Vector2& value)     : value_(0) { this->assignValue(value); }           ///< Constructor: Assigns the given value and sets the type.
     290            inline MultiType(const orxonox::Vector3& value)     : value_(0) { this->assignValue(value); }           ///< Constructor: Assigns the given value and sets the type.
     291            inline MultiType(const orxonox::Vector4& value)     : value_(0) { this->assignValue(value); }           ///< Constructor: Assigns the given value and sets the type.
     292            inline MultiType(const orxonox::ColourValue& value) : value_(0) { this->assignValue(value); }           ///< Constructor: Assigns the given value and sets the type.
     293            inline MultiType(const orxonox::Quaternion& value)  : value_(0) { this->assignValue(value); }           ///< Constructor: Assigns the given value and sets the type.
     294            inline MultiType(const orxonox::Radian& value)      : value_(0) { this->assignValue(value); }           ///< Constructor: Assigns the given value and sets the type.
     295            inline MultiType(const orxonox::Degree& value)      : value_(0) { this->assignValue(value); }           ///< Constructor: Assigns the given value and sets the type.
     296            inline MultiType(const orxonox::mbool& value)       : value_(0) { this->assignValue((bool)value); }     ///< Constructor: Assigns the given mbool and converts it to bool.
     297            inline MultiType(const char* value)                 : value_(0) { this->setValue(std::string(value)); } ///< Constructor: Converts the char array to a std::string, assigns the value and sets the type.
     298            inline MultiType(const MultiType& other)            : value_(0) { this->setValue(other); }              ///< Copyconstructor: Assigns value and type of the other MultiType.
     299            inline MultiType(MT_Type::Value type)               : value_(0) { this->setType(type); }                ///< Constructor: Sets the type, the next assignment will determine the value.
     300
     301            /// Destructor: Deletes the MT_Value.
    274302            inline ~MultiType() { if (this->value_) { delete this->value_; } }
    275303
    276             template <typename V> inline MultiType& operator=(const V& value)         { this->setValue(value); return (*this); } /** @brief Assigns a new value. The value will be converted to the current type of the MultiType. */
    277             template <typename V> inline MultiType& operator=(V* value)               { this->setValue(value); return (*this); } /** @brief Assigns a pointer. */
    278             inline                       MultiType& operator=(const MultiType& other) { this->setValue(other); return (*this); } /** @brief Assigns the value of the other MultiType and converts it to the current type of the MultiType. */
    279             inline                       MultiType& operator=(MT_Type::Value type)    { this->setType(type);   return (*this); } /** @brief Resets the value and changes the type. */
     304            template <typename V> inline MultiType& operator=(const V& value)         { this->setValue(value); return (*this); } ///< Assigns a new value. The value will be converted to the current type of the MultiType.
     305            template <typename V> inline MultiType& operator=(V* value)               { this->setValue(value); return (*this); } ///< Assigns a pointer.
     306            inline                       MultiType& operator=(const MultiType& other) { this->setValue(other); return (*this); } ///< Assigns the value of the other MultiType and converts it to the current type of the MultiType.
     307            inline                       MultiType& operator=(MT_Type::Value type)    { this->setType(type);   return (*this); } ///< Resets the value and changes the type.
    280308
    281309            inline bool                                   setValue(const char& value);
    … …  
    303331            inline bool                                   setValue(const orxonox::Degree& value);
    304332            inline bool                                   setValue(const char* value);
    305             /** @brief Assigns a pointer. */
     333            /// Assigns a pointer.
    306334            template <typename V> inline bool setValue(V* value)
    307335            {
    … …  
    311339                    return this->assignValue     (static_cast<void*>(const_cast<typename Loki::TypeTraits<V>::UnqualifiedType*>(value)));
    312340            }
    313             /** @brief Assigns the value of the other MultiType and converts it to the current type. */
     341            /// Assigns the value of the other MultiType and converts it to the current type.
    314342            bool                                          setValue(const MultiType& other) { if (this->value_) { return this->value_->assimilate(other); } else { if (other.value_) { this->value_ = other.value_->clone(); } return true; } }
    315             /** @brief Changes the type to T and assigns the new value (which might be of another type than T - it gets converted). */
     343            /// Changes the type to T and assigns the new value (which might be of another type than T - it gets converted).
    316344            template <typename T, typename V> inline bool setValue(const V& value) { this->setType<T>(); return this->setValue(value); }
    317345
    318346
    319             /** @brief Copies the other MultiType by assigning value and type. */
     347            /// Copies the other MultiType by assigning value and type.
    320348            inline void                       copy(const MultiType& other)    { if (this == &other) { return; } if (this->value_) { delete this->value_; } this->value_ = (other.value_) ? other.value_->clone() : 0; }
    321349
    322             template <typename T> inline bool convert()                       { return this->setValue<T>((typename Loki::TypeTraits<T>::UnqualifiedReferredType)(*this));  } /** @brief Converts the current value to type T. */
    323             inline bool                       convert(const MultiType& other) { return this->convert(other.getType()); } /** @brief Converts the current value to the type of the other MultiType. */
     350            /// Converts the current value to type T.
     351            template <typename T> inline bool convert()                       { return this->setValue<T>((typename Loki::TypeTraits<T>::UnqualifiedReferredType)(*this));  }
     352            /// Converts the current value to the type of the other MultiType.
     353            inline bool                       convert(const MultiType& other) { return this->convert(other.getType()); }
    324354            bool                              convert(MT_Type::Value type);
    325355
    326             /** @brief Current content gets deleted. New type is MT_Type::Null */
     356            /// Current content gets deleted. New type is MT_Type::Null
    327357            inline void                       reset()                         { if (this->value_) delete this->value_; this->value_ = 0; }
    328             /** @brief Current content gets overridden with default zero value */
     358            /// Current content gets overridden with default zero value
    329359            inline void                       resetValue()                    { if (this->value_) this->value_->reset(); }
    330360
    331             template <typename T> inline void setType()                       { this->assignValue(typename Loki::TypeTraits<T>::UnqualifiedReferredType()); } /** @brief Resets the value and changes the internal type to T. */
    332             inline void                       setType(const MultiType& other) { this->setType(other.getType());                                             } /** @brief Resets the value and changes the internal type to the type of the other MultiType. */
    333             inline void                       setType(MT_Type::Value type)    { this->reset(); this->convert(type); this->resetValue();                     } /** @brief Resets the value and changes the internal type to the given type. */
    334 
    335             /** @brief Returns the current type. */
     361            /// Resets the value and changes the internal type to T.
     362            template <typename T> inline void setType()                       { this->assignValue(typename Loki::TypeTraits<T>::UnqualifiedReferredType()); }
     363            /// Resets the value and changes the internal type to the type of the other MultiType.
     364            inline void                       setType(const MultiType& other) { this->setType(other.getType());                                             }
     365            /// Resets the value and changes the internal type to the given type.
     366            inline void                       setType(MT_Type::Value type)    { this->reset(); this->convert(type); this->resetValue();                     }
     367
     368            /// Returns the current type.
    336369            inline MT_Type::Value             getType()                   const { return (this->value_) ? this->value_->type_ : MT_Type::Null; }
    337             /** @brief Returns true if the current type equals the given type. */
     370            /// Returns true if the current type equals the given type.
    338371            inline bool                       isType(MT_Type::Value type) const { return (this->value_) ? (this->value_->type_ == type) : (type == MT_Type::Null); }
    339             /** @brief Returns true if the current type is T. */
     372            /// Returns true if the current type is T.
    340373            template <typename T> inline bool isType()                    const { return false; } // Only works for specialized values - see below
    341374            std::string                       getTypename()               const;
    342375
    343             /** @brief Saves the value of the MT to a bytestream (pointed at by mem) and increases mem pointer by size of MT */
     376            /// Saves the value of the MT to a bytestream (pointed at by mem) and increases mem pointer by size of MT
    344377            inline void                       exportData(uint8_t*& mem) const { assert(sizeof(MT_Type::Value)<=8); *static_cast<uint8_t*>(mem) = this->getType(); mem+=sizeof(uint8_t); this->value_->exportData(mem); }
    345             /** @brief Loads the value of the MT from a bytestream (pointed at by mem) and increases mem pointer by size of MT */
     378            /// Loads the value of the MT from a bytestream (pointed at by mem) and increases mem pointer by size of MT
    346379            inline void                       importData(uint8_t*& mem) { assert(sizeof(MT_Type::Value)<=8); this->setType(static_cast<MT_Type::Value>(*static_cast<uint8_t*>(mem))); mem+=sizeof(uint8_t); this->value_->importData(mem); }
    347             /** @brief Saves the value of the MT to a bytestream and increases pointer to bytestream by size of MT */
     380            /// Saves the value of the MT to a bytestream and increases pointer to bytestream by size of MT
    348381            inline uint8_t*&                  operator << (uint8_t*& mem) { importData(mem); return mem; }
    349             /** @brief Loads the value of the MT to a bytestream and increases pointer to bytestream by size of MT */
     382            /// Loads the value of the MT to a bytestream and increases pointer to bytestream by size of MT
    350383            inline void                       operator >> (uint8_t*& mem) const { exportData(mem); }
    351384            inline uint32_t                   getNetworkSize() const { assert(this->value_); return this->value_->getSize() + sizeof(uint8_t); }
    352385
    353             /** @brief Checks whether the value is a default one. */
     386            /// Checks whether the value is a default one (assigned after a failed conversion)
    354387            bool                              hasDefaultValue() const { return this->value_->hasDefaultValue(); }
    355388
    356             /** @brief Checks if the MT contains no value. */
     389            /// Checks if the MT contains no value.
    357390            bool                              null() const { return (!this->value_); }
    358391
    … …  
    380413            operator orxonox::Radian()       const;
    381414            operator orxonox::Degree()       const;
    382             /** @brief Returns the current value, converted to a T* pointer. */
     415            /// Returns the current value, converted to a T* pointer.
    383416            template <class T> operator T*() const { return (static_cast<T*>(this->operator void*())); }
    384417
    385             inline bool getValue(char*                 value) const { if (this->value_) { return this->value_->getValue(value); } return false; } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    386             inline bool getValue(unsigned char*        value) const { if (this->value_) { return this->value_->getValue(value); } return false; } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    387             inline bool getValue(short*                value) const { if (this->value_) { return this->value_->getValue(value); } return false; } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    388             inline bool getValue(unsigned short*       value) const { if (this->value_) { return this->value_->getValue(value); } return false; } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    389             inline bool getValue(int*                  value) const { if (this->value_) { return this->value_->getValue(value); } return false; } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    390             inline bool getValue(unsigned int*         value) const { if (this->value_) { return this->value_->getValue(value); } return false; } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    391             inline bool getValue(long*                 value) const { if (this->value_) { return this->value_->getValue(value); } return false; } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    392             inline bool getValue(unsigned long*        value) const { if (this->value_) { return this->value_->getValue(value); } return false; } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    393             inline bool getValue(long long*            value) const { if (this->value_) { return this->value_->getValue(value); } return false; } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    394             inline bool getValue(unsigned long long*   value) const { if (this->value_) { return this->value_->getValue(value); } return false; } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    395             inline bool getValue(float*                value) const { if (this->value_) { return this->value_->getValue(value); } return false; } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    396             inline bool getValue(double*               value) const { if (this->value_) { return this->value_->getValue(value); } return false; } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    397             inline bool getValue(long double*          value) const { if (this->value_) { return this->value_->getValue(value); } return false; } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    398             inline bool getValue(bool*                 value) const { if (this->value_) { return this->value_->getValue(value); } return false; } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    399             inline bool getValue(void**                value) const { if (this->value_) { return this->value_->getValue(value); } return false; } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    400             inline bool getValue(std::string*          value) const { if (this->value_) { return this->value_->getValue(value); } return false; } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    401             inline bool getValue(orxonox::Vector2*     value) const { if (this->value_) { return this->value_->getValue(value); } return false; } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    402             inline bool getValue(orxonox::Vector3*     value) const { if (this->value_) { return this->value_->getValue(value); } return false; } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    403             inline bool getValue(orxonox::Vector4*     value) const { if (this->value_) { return this->value_->getValue(value); } return false; } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    404             inline bool getValue(orxonox::ColourValue* value) const { if (this->value_) { return this->value_->getValue(value); } return false; } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    405             inline bool getValue(orxonox::Quaternion*  value) const { if (this->value_) { return this->value_->getValue(value); } return false; } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    406             inline bool getValue(orxonox::Radian*      value) const { if (this->value_) { return this->value_->getValue(value); } return false; } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    407             inline bool getValue(orxonox::Degree*      value) const { if (this->value_) { return this->value_->getValue(value); } return false; } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    408 
    409             inline char                     getChar()             const { return this->operator char();                 } /** @brief Returns the current value, converted to the requested type. */
    410             inline unsigned char            getUnsignedChar()     const { return this->operator unsigned char();        } /** @brief Returns the current value, converted to the requested type. */
    411             inline short                    getShort()            const { return this->operator short();                } /** @brief Returns the current value, converted to the requested type. */
    412             inline unsigned short           getUnsignedShort()    const { return this->operator unsigned short();       } /** @brief Returns the current value, converted to the requested type. */
    413             inline int                      getInt()              const { return this->operator int();                  } /** @brief Returns the current value, converted to the requested type. */
    414             inline unsigned int             getUnsignedInt()      const { return this->operator unsigned int();         } /** @brief Returns the current value, converted to the requested type. */
    415             inline long                     getLong()             const { return this->operator long();                 } /** @brief Returns the current value, converted to the requested type. */
    416             inline unsigned long            getUnsignedLong()     const { return this->operator unsigned long();        } /** @brief Returns the current value, converted to the requested type. */
    417             inline long long                getLongLong()         const { return this->operator long long();            } /** @brief Returns the current value, converted to the requested type. */
    418             inline unsigned long long       getUnsignedLongLong() const { return this->operator unsigned long long();   } /** @brief Returns the current value, converted to the requested type. */
    419             inline float                    getFloat()            const { return this->operator float();                } /** @brief Returns the current value, converted to the requested type. */
    420             inline double                   getDouble()           const { return this->operator double();               } /** @brief Returns the current value, converted to the requested type. */
    421             inline long double              getLongDouble()       const { return this->operator long double();          } /** @brief Returns the current value, converted to the requested type. */
    422             inline bool                     getBool()             const { return this->operator bool();                 } /** @brief Returns the current value, converted to the requested type. */
    423             inline void*                    getVoid()             const { return this->operator void*();                } /** @brief Returns the current value, converted to the requested type. */
    424             inline std::string              getString()           const { return this->operator std::string();          } /** @brief Returns the current value, converted to the requested type. */
    425             inline orxonox::Vector2         getVector2()          const { return this->operator orxonox::Vector2();     } /** @brief Returns the current value, converted to the requested type. */
    426             inline orxonox::Vector3         getVector3()          const { return this->operator orxonox::Vector3();     } /** @brief Returns the current value, converted to the requested type. */
    427             inline orxonox::Vector4         getVector4()          const { return this->operator orxonox::Vector4();     } /** @brief Returns the current value, converted to the requested type. */
    428             inline orxonox::ColourValue     getColourValue()      const { return this->operator orxonox::ColourValue(); } /** @brief Returns the current value, converted to the requested type. */
    429             inline orxonox::Quaternion      getQuaternion()       const { return this->operator orxonox::Quaternion();  } /** @brief Returns the current value, converted to the requested type. */
    430             inline orxonox::Radian          getRadian()           const { return this->operator orxonox::Radian();      } /** @brief Returns the current value, converted to the requested type. */
    431             inline orxonox::Degree          getDegree()           const { return this->operator orxonox::Degree();      } /** @brief Returns the current value, converted to the requested type. */
    432             template <typename T> inline T* getPointer()          const { return static_cast<T*>(this->getVoid());      } /** @brief Returns the current value, converted to a T* pointer. */
     418            inline bool getValue(char*                 value) const { if (this->value_) { return this->value_->getValue(value); } return false; } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     419            inline bool getValue(unsigned char*        value) const { if (this->value_) { return this->value_->getValue(value); } return false; } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     420            inline bool getValue(short*                value) const { if (this->value_) { return this->value_->getValue(value); } return false; } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     421            inline bool getValue(unsigned short*       value) const { if (this->value_) { return this->value_->getValue(value); } return false; } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     422            inline bool getValue(int*                  value) const { if (this->value_) { return this->value_->getValue(value); } return false; } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     423            inline bool getValue(unsigned int*         value) const { if (this->value_) { return this->value_->getValue(value); } return false; } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     424            inline bool getValue(long*                 value) const { if (this->value_) { return this->value_->getValue(value); } return false; } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     425            inline bool getValue(unsigned long*        value) const { if (this->value_) { return this->value_->getValue(value); } return false; } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     426            inline bool getValue(long long*            value) const { if (this->value_) { return this->value_->getValue(value); } return false; } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     427            inline bool getValue(unsigned long long*   value) const { if (this->value_) { return this->value_->getValue(value); } return false; } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     428            inline bool getValue(float*                value) const { if (this->value_) { return this->value_->getValue(value); } return false; } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     429            inline bool getValue(double*               value) const { if (this->value_) { return this->value_->getValue(value); } return false; } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     430            inline bool getValue(long double*          value) const { if (this->value_) { return this->value_->getValue(value); } return false; } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     431            inline bool getValue(bool*                 value) const { if (this->value_) { return this->value_->getValue(value); } return false; } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     432            inline bool getValue(void**                value) const { if (this->value_) { return this->value_->getValue(value); } return false; } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     433            inline bool getValue(std::string*          value) const { if (this->value_) { return this->value_->getValue(value); } return false; } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     434            inline bool getValue(orxonox::Vector2*     value) const { if (this->value_) { return this->value_->getValue(value); } return false; } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     435            inline bool getValue(orxonox::Vector3*     value) const { if (this->value_) { return this->value_->getValue(value); } return false; } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     436            inline bool getValue(orxonox::Vector4*     value) const { if (this->value_) { return this->value_->getValue(value); } return false; } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     437            inline bool getValue(orxonox::ColourValue* value) const { if (this->value_) { return this->value_->getValue(value); } return false; } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     438            inline bool getValue(orxonox::Quaternion*  value) const { if (this->value_) { return this->value_->getValue(value); } return false; } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     439            inline bool getValue(orxonox::Radian*      value) const { if (this->value_) { return this->value_->getValue(value); } return false; } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     440            inline bool getValue(orxonox::Degree*      value) const { if (this->value_) { return this->value_->getValue(value); } return false; } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     441
     442            inline char                     getChar()             const { return this->operator char();                 } ///< Returns the current value, converted to the requested type.
     443            inline unsigned char            getUnsignedChar()     const { return this->operator unsigned char();        } ///< Returns the current value, converted to the requested type.
     444            inline short                    getShort()            const { return this->operator short();                } ///< Returns the current value, converted to the requested type.
     445            inline unsigned short           getUnsignedShort()    const { return this->operator unsigned short();       } ///< Returns the current value, converted to the requested type.
     446            inline int                      getInt()              const { return this->operator int();                  } ///< Returns the current value, converted to the requested type.
     447            inline unsigned int             getUnsignedInt()      const { return this->operator unsigned int();         } ///< Returns the current value, converted to the requested type.
     448            inline long                     getLong()             const { return this->operator long();                 } ///< Returns the current value, converted to the requested type.
     449            inline unsigned long            getUnsignedLong()     const { return this->operator unsigned long();        } ///< Returns the current value, converted to the requested type.
     450            inline long long                getLongLong()         const { return this->operator long long();            } ///< Returns the current value, converted to the requested type.
     451            inline unsigned long long       getUnsignedLongLong() const { return this->operator unsigned long long();   } ///< Returns the current value, converted to the requested type.
     452            inline float                    getFloat()            const { return this->operator float();                } ///< Returns the current value, converted to the requested type.
     453            inline double                   getDouble()           const { return this->operator double();               } ///< Returns the current value, converted to the requested type.
     454            inline long double              getLongDouble()       const { return this->operator long double();          } ///< Returns the current value, converted to the requested type.
     455            inline bool                     getBool()             const { return this->operator bool();                 } ///< Returns the current value, converted to the requested type.
     456            inline void*                    getVoid()             const { return this->operator void*();                } ///< Returns the current value, converted to the requested type.
     457            inline std::string              getString()           const { return this->operator std::string();          } ///< Returns the current value, converted to the requested type.
     458            inline orxonox::Vector2         getVector2()          const { return this->operator orxonox::Vector2();     } ///< Returns the current value, converted to the requested type.
     459            inline orxonox::Vector3         getVector3()          const { return this->operator orxonox::Vector3();     } ///< Returns the current value, converted to the requested type.
     460            inline orxonox::Vector4         getVector4()          const { return this->operator orxonox::Vector4();     } ///< Returns the current value, converted to the requested type.
     461            inline orxonox::ColourValue     getColourValue()      const { return this->operator orxonox::ColourValue(); } ///< Returns the current value, converted to the requested type.
     462            inline orxonox::Quaternion      getQuaternion()       const { return this->operator orxonox::Quaternion();  } ///< Returns the current value, converted to the requested type.
     463            inline orxonox::Radian          getRadian()           const { return this->operator orxonox::Radian();      } ///< Returns the current value, converted to the requested type.
     464            inline orxonox::Degree          getDegree()           const { return this->operator orxonox::Degree();      } ///< Returns the current value, converted to the requested type.
     465            template <typename T> inline T* getPointer()          const { return static_cast<T*>(this->getVoid());      } ///< Returns the current value, converted to a T* pointer.
    433466
    434467        private:
    435             inline bool assignValue(const char& value)                 { if (this->value_ && this->value_->type_ == MT_Type::Char)             { return this->value_->setValue(value); } else { this->changeValueContainer<char>(value);                 return true; } } /** @brief Assigns a new value by changing type and creating a new container. */
    436             inline bool assignValue(const unsigned char& value)        { if (this->value_ && this->value_->type_ == MT_Type::UnsignedChar)     { return this->value_->setValue(value); } else { this->changeValueContainer<unsigned char>(value);        return true; } } /** @brief Assigns a new value by changing type and creating a new container. */
    437             inline bool assignValue(const short& value)                { if (this->value_ && this->value_->type_ == MT_Type::Short)            { return this->value_->setValue(value); } else { this->changeValueContainer<short>(value);                return true; } } /** @brief Assigns a new value by changing type and creating a new container. */
    438             inline bool assignValue(const unsigned short& value)       { if (this->value_ && this->value_->type_ == MT_Type::UnsignedShort)    { return this->value_->setValue(value); } else { this->changeValueContainer<unsigned short>(value);       return true; } } /** @brief Assigns a new value by changing type and creating a new container. */
    439             inline bool assignValue(const int& value)                  { if (this->value_ && this->value_->type_ == MT_Type::Int)              { return this->value_->setValue(value); } else { this->changeValueContainer<int>(value);                  return true; } } /** @brief Assigns a new value by changing type and creating a new container. */
    440             inline bool assignValue(const unsigned int& value)         { if (this->value_ && this->value_->type_ == MT_Type::UnsignedInt)      { return this->value_->setValue(value); } else { this->changeValueContainer<unsigned int>(value);         return true; } } /** @brief Assigns a new value by changing type and creating a new container. */
    441             inline bool assignValue(const long& value)                 { if (this->value_ && this->value_->type_ == MT_Type::Long)             { return this->value_->setValue(value); } else { this->changeValueContainer<long>(value);                 return true; } } /** @brief Assigns a new value by changing type and creating a new container. */
    442             inline bool assignValue(const unsigned long& value)        { if (this->value_ && this->value_->type_ == MT_Type::UnsignedLong)     { return this->value_->setValue(value); } else { this->changeValueContainer<unsigned long>(value);        return true; } } /** @brief Assigns a new value by changing type and creating a new container. */
    443             inline bool assignValue(const long long& value)            { if (this->value_ && this->value_->type_ == MT_Type::LongLong)         { return this->value_->setValue(value); } else { this->changeValueContainer<long long>(value);            return true; } } /** @brief Assigns a new value by changing type and creating a new container. */
    444             inline bool assignValue(const unsigned long long& value)   { if (this->value_ && this->value_->type_ == MT_Type::UnsignedLongLong) { return this->value_->setValue(value); } else { this->changeValueContainer<unsigned long long>(value);   return true; } } /** @brief Assigns a new value by changing type and creating a new container. */
    445             inline bool assignValue(const float& value)                { if (this->value_ && this->value_->type_ == MT_Type::Float)            { return this->value_->setValue(value); } else { this->changeValueContainer<float>(value);                return true; } } /** @brief Assigns a new value by changing type and creating a new container. */
    446             inline bool assignValue(const double& value)               { if (this->value_ && this->value_->type_ == MT_Type::Double)           { return this->value_->setValue(value); } else { this->changeValueContainer<double>(value);               return true; } } /** @brief Assigns a new value by changing type and creating a new container. */
    447             inline bool assignValue(const long double& value)          { if (this->value_ && this->value_->type_ == MT_Type::LongDouble)       { return this->value_->setValue(value); } else { this->changeValueContainer<long double>(value);          return true; } } /** @brief Assigns a new value by changing type and creating a new container. */
    448             inline bool assignValue(const bool& value)                 { if (this->value_ && this->value_->type_ == MT_Type::Bool)             { return this->value_->setValue(value); } else { this->changeValueContainer<bool>(value);                 return true; } } /** @brief Assigns a new value by changing type and creating a new container. */
    449             inline bool assignValue(      void* const& value)          { if (this->value_ && this->value_->type_ == MT_Type::VoidPointer)      { return this->value_->setValue(value); } else { this->changeValueContainer<void*>(value);                return true; } } /** @brief Assigns a new value by changing type and creating a new container. */
    450             inline bool assignValue(const std::string& value)          { if (this->value_ && this->value_->type_ == MT_Type::String)           { return this->value_->setValue(value); } else { this->changeValueContainer<std::string>(value);          return true; } } /** @brief Assigns a new value by changing type and creating a new container. */
    451             inline bool assignValue(const orxonox::Vector2& value)     { if (this->value_ && this->value_->type_ == MT_Type::Vector2)          { return this->value_->setValue(value); } else { this->changeValueContainer<orxonox::Vector2>(value);     return true; } } /** @brief Assigns a new value by changing type and creating a new container. */
    452             inline bool assignValue(const orxonox::Vector3& value)     { if (this->value_ && this->value_->type_ == MT_Type::Vector3)          { return this->value_->setValue(value); } else { this->changeValueContainer<orxonox::Vector3>(value);     return true; } } /** @brief Assigns a new value by changing type and creating a new container. */
    453             inline bool assignValue(const orxonox::Vector4& value)     { if (this->value_ && this->value_->type_ == MT_Type::Vector4)          { return this->value_->setValue(value); } else { this->changeValueContainer<orxonox::Vector4>(value);     return true; } } /** @brief Assigns a new value by changing type and creating a new container. */
    454             inline bool assignValue(const orxonox::ColourValue& value) { if (this->value_ && this->value_->type_ == MT_Type::ColourValue)      { return this->value_->setValue(value); } else { this->changeValueContainer<orxonox::ColourValue>(value); return true; } } /** @brief Assigns a new value by changing type and creating a new container. */
    455             inline bool assignValue(const orxonox::Quaternion& value)  { if (this->value_ && this->value_->type_ == MT_Type::Quaternion)       { return this->value_->setValue(value); } else { this->changeValueContainer<orxonox::Quaternion>(value);  return true; } } /** @brief Assigns a new value by changing type and creating a new container. */
    456             inline bool assignValue(const orxonox::Radian& value)      { if (this->value_ && this->value_->type_ == MT_Type::Radian)           { return this->value_->setValue(value); } else { this->changeValueContainer<orxonox::Radian>(value);      return true; } } /** @brief Assigns a new value by changing type and creating a new container. */
    457             inline bool assignValue(const orxonox::Degree& value)      { if (this->value_ && this->value_->type_ == MT_Type::Degree)           { return this->value_->setValue(value); } else { this->changeValueContainer<orxonox::Degree>(value);      return true; } } /** @brief Assigns a new value by changing type and creating a new container. */
    458 
    459             /** @brief Changes the value container. */
     468            inline bool assignValue(const char& value)                 { if (this->value_ && this->value_->type_ == MT_Type::Char)             { return this->value_->setValue(value); } else { this->changeValueContainer<char>(value);                 return true; } } ///< Assigns a new value by changing type and creating a new container.
     469            inline bool assignValue(const unsigned char& value)        { if (this->value_ && this->value_->type_ == MT_Type::UnsignedChar)     { return this->value_->setValue(value); } else { this->changeValueContainer<unsigned char>(value);        return true; } } ///< Assigns a new value by changing type and creating a new container.
     470            inline bool assignValue(const short& value)                { if (this->value_ && this->value_->type_ == MT_Type::Short)            { return this->value_->setValue(value); } else { this->changeValueContainer<short>(value);                return true; } } ///< Assigns a new value by changing type and creating a new container.
     471            inline bool assignValue(const unsigned short& value)       { if (this->value_ && this->value_->type_ == MT_Type::UnsignedShort)    { return this->value_->setValue(value); } else { this->changeValueContainer<unsigned short>(value);       return true; } } ///< Assigns a new value by changing type and creating a new container.
     472            inline bool assignValue(const int& value)                  { if (this->value_ && this->value_->type_ == MT_Type::Int)              { return this->value_->setValue(value); } else { this->changeValueContainer<int>(value);                  return true; } } ///< Assigns a new value by changing type and creating a new container.
     473            inline bool assignValue(const unsigned int& value)         { if (this->value_ && this->value_->type_ == MT_Type::UnsignedInt)      { return this->value_->setValue(value); } else { this->changeValueContainer<unsigned int>(value);         return true; } } ///< Assigns a new value by changing type and creating a new container.
     474            inline bool assignValue(const long& value)                 { if (this->value_ && this->value_->type_ == MT_Type::Long)             { return this->value_->setValue(value); } else { this->changeValueContainer<long>(value);                 return true; } } ///< Assigns a new value by changing type and creating a new container.
     475            inline bool assignValue(const unsigned long& value)        { if (this->value_ && this->value_->type_ == MT_Type::UnsignedLong)     { return this->value_->setValue(value); } else { this->changeValueContainer<unsigned long>(value);        return true; } } ///< Assigns a new value by changing type and creating a new container.
     476            inline bool assignValue(const long long& value)            { if (this->value_ && this->value_->type_ == MT_Type::LongLong)         { return this->value_->setValue(value); } else { this->changeValueContainer<long long>(value);            return true; } } ///< Assigns a new value by changing type and creating a new container.
     477            inline bool assignValue(const unsigned long long& value)   { if (this->value_ && this->value_->type_ == MT_Type::UnsignedLongLong) { return this->value_->setValue(value); } else { this->changeValueContainer<unsigned long long>(value);   return true; } } ///< Assigns a new value by changing type and creating a new container.
     478            inline bool assignValue(const float& value)                { if (this->value_ && this->value_->type_ == MT_Type::Float)            { return this->value_->setValue(value); } else { this->changeValueContainer<float>(value);                return true; } } ///< Assigns a new value by changing type and creating a new container.
     479            inline bool assignValue(const double& value)               { if (this->value_ && this->value_->type_ == MT_Type::Double)           { return this->value_->setValue(value); } else { this->changeValueContainer<double>(value);               return true; } } ///< Assigns a new value by changing type and creating a new container.
     480            inline bool assignValue(const long double& value)          { if (this->value_ && this->value_->type_ == MT_Type::LongDouble)       { return this->value_->setValue(value); } else { this->changeValueContainer<long double>(value);          return true; } } ///< Assigns a new value by changing type and creating a new container.
     481            inline bool assignValue(const bool& value)                 { if (this->value_ && this->value_->type_ == MT_Type::Bool)             { return this->value_->setValue(value); } else { this->changeValueContainer<bool>(value);                 return true; } } ///< Assigns a new value by changing type and creating a new container.
     482            inline bool assignValue(      void* const& value)          { if (this->value_ && this->value_->type_ == MT_Type::VoidPointer)      { return this->value_->setValue(value); } else { this->changeValueContainer<void*>(value);                return true; } } ///< Assigns a new value by changing type and creating a new container.
     483            inline bool assignValue(const std::string& value)          { if (this->value_ && this->value_->type_ == MT_Type::String)           { return this->value_->setValue(value); } else { this->changeValueContainer<std::string>(value);          return true; } } ///< Assigns a new value by changing type and creating a new container.
     484            inline bool assignValue(const orxonox::Vector2& value)     { if (this->value_ && this->value_->type_ == MT_Type::Vector2)          { return this->value_->setValue(value); } else { this->changeValueContainer<orxonox::Vector2>(value);     return true; } } ///< Assigns a new value by changing type and creating a new container.
     485            inline bool assignValue(const orxonox::Vector3& value)     { if (this->value_ && this->value_->type_ == MT_Type::Vector3)          { return this->value_->setValue(value); } else { this->changeValueContainer<orxonox::Vector3>(value);     return true; } } ///< Assigns a new value by changing type and creating a new container.
     486            inline bool assignValue(const orxonox::Vector4& value)     { if (this->value_ && this->value_->type_ == MT_Type::Vector4)          { return this->value_->setValue(value); } else { this->changeValueContainer<orxonox::Vector4>(value);     return true; } } ///< Assigns a new value by changing type and creating a new container.
     487            inline bool assignValue(const orxonox::ColourValue& value) { if (this->value_ && this->value_->type_ == MT_Type::ColourValue)      { return this->value_->setValue(value); } else { this->changeValueContainer<orxonox::ColourValue>(value); return true; } } ///< Assigns a new value by changing type and creating a new container.
     488            inline bool assignValue(const orxonox::Quaternion& value)  { if (this->value_ && this->value_->type_ == MT_Type::Quaternion)       { return this->value_->setValue(value); } else { this->changeValueContainer<orxonox::Quaternion>(value);  return true; } } ///< Assigns a new value by changing type and creating a new container.
     489            inline bool assignValue(const orxonox::Radian& value)      { if (this->value_ && this->value_->type_ == MT_Type::Radian)           { return this->value_->setValue(value); } else { this->changeValueContainer<orxonox::Radian>(value);      return true; } } ///< Assigns a new value by changing type and creating a new container.
     490            inline bool assignValue(const orxonox::Degree& value)      { if (this->value_ && this->value_->type_ == MT_Type::Degree)           { return this->value_->setValue(value); } else { this->changeValueContainer<orxonox::Degree>(value);      return true; } } ///< Assigns a new value by changing type and creating a new container.
     491
     492            /// Changes the value container.
    460493            template <typename T> inline void changeValueContainer(const T& value) { if (this->value_) { delete this->value_; } this->createNewValueContainer<T>(value); }
    461             /** @brief Creates a new value container (works only with specialized types). */
     494            /// Creates a new value container (works only with specialized types).
    462495            template <typename T>        void createNewValueContainer(const T& value) { /* STATIC ASSERT */ *****value; return false; }
    463496
    … …  
    465498    };
    466499
    467     /** @brief Puts the MultiType on a stream by using the native << operator of the current type. */
     500    /// Puts the MultiType on a stream by using the native << operator of the current type.
    468501    _UtilExport inline std::ostream& operator<<(std::ostream& outstream, const MultiType& mt) { if (mt.value_) { mt.value_->toString(outstream); } return outstream; }
    469502
    470     template <> inline bool MultiType::isType<char>()                 const { return (this->value_ && this->value_->type_ == MT_Type::Char);             } /** @brief Returns true if the current type equals the given type. */
    471     template <> inline bool MultiType::isType<unsigned char>()        const { return (this->value_ && this->value_->type_ == MT_Type::UnsignedChar);     } /** @brief Returns true if the current type equals the given type. */
    472     template <> inline bool MultiType::isType<short>()                const { return (this->value_ && this->value_->type_ == MT_Type::Short);            } /** @brief Returns true if the current type equals the given type. */
    473     template <> inline bool MultiType::isType<unsigned short>()       const { return (this->value_ && this->value_->type_ == MT_Type::UnsignedShort);    } /** @brief Returns true if the current type equals the given type. */
    474     template <> inline bool MultiType::isType<int>()                  const { return (this->value_ && this->value_->type_ == MT_Type::Int);              } /** @brief Returns true if the current type equals the given type. */
    475     template <> inline bool MultiType::isType<unsigned int>()         const { return (this->value_ && this->value_->type_ == MT_Type::UnsignedInt);      } /** @brief Returns true if the current type equals the given type. */
    476     template <> inline bool MultiType::isType<long>()                 const { return (this->value_ && this->value_->type_ == MT_Type::Long);             } /** @brief Returns true if the current type equals the given type. */
    477     template <> inline bool MultiType::isType<unsigned long>()        const { return (this->value_ && this->value_->type_ == MT_Type::UnsignedLong);     } /** @brief Returns true if the current type equals the given type. */
    478     template <> inline bool MultiType::isType<long long>()            const { return (this->value_ && this->value_->type_ == MT_Type::LongLong);         } /** @brief Returns true if the current type equals the given type. */
    479     template <> inline bool MultiType::isType<unsigned long long>()   const { return (this->value_ && this->value_->type_ == MT_Type::UnsignedLongLong); } /** @brief Returns true if the current type equals the given type. */
    480     template <> inline bool MultiType::isType<float>()                const { return (this->value_ && this->value_->type_ == MT_Type::Float);            } /** @brief Returns true if the current type equals the given type. */
    481     template <> inline bool MultiType::isType<double>()               const { return (this->value_ && this->value_->type_ == MT_Type::Double);           } /** @brief Returns true if the current type equals the given type. */
    482     template <> inline bool MultiType::isType<long double>()          const { return (this->value_ && this->value_->type_ == MT_Type::LongDouble);       } /** @brief Returns true if the current type equals the given type. */
    483     template <> inline bool MultiType::isType<bool>()                 const { return (this->value_ && this->value_->type_ == MT_Type::Bool);             } /** @brief Returns true if the current type equals the given type. */
    484     template <> inline bool MultiType::isType<void*>()                const { return (this->value_ && this->value_->type_ == MT_Type::VoidPointer);      } /** @brief Returns true if the current type equals the given type. */
    485     template <> inline bool MultiType::isType<std::string>()          const { return (this->value_ && this->value_->type_ == MT_Type::String);           } /** @brief Returns true if the current type equals the given type. */
    486     template <> inline bool MultiType::isType<orxonox::Vector2>()     const { return (this->value_ && this->value_->type_ == MT_Type::Vector2);          } /** @brief Returns true if the current type equals the given type. */
    487     template <> inline bool MultiType::isType<orxonox::Vector3>()     const { return (this->value_ && this->value_->type_ == MT_Type::Vector3);          } /** @brief Returns true if the current type equals the given type. */
    488     template <> inline bool MultiType::isType<orxonox::Vector4>()     const { return (this->value_ && this->value_->type_ == MT_Type::Vector4);          } /** @brief Returns true if the current type equals the given type. */
    489     template <> inline bool MultiType::isType<orxonox::ColourValue>() const { return (this->value_ && this->value_->type_ == MT_Type::ColourValue);      } /** @brief Returns true if the current type equals the given type. */
    490     template <> inline bool MultiType::isType<orxonox::Quaternion>()  const { return (this->value_ && this->value_->type_ == MT_Type::Quaternion);       } /** @brief Returns true if the current type equals the given type. */
    491     template <> inline bool MultiType::isType<orxonox::Radian>()      const { return (this->value_ && this->value_->type_ == MT_Type::Radian);           } /** @brief Returns true if the current type equals the given type. */
    492     template <> inline bool MultiType::isType<orxonox::Degree>()      const { return (this->value_ && this->value_->type_ == MT_Type::Degree);           } /** @brief Returns true if the current type equals the given type. */
    493 
    494     template <> inline bool MultiType::convert<void>()                 { this->reset(); return true; } /** @brief Deletes the content, type becomes MT_Type::Null. */
     503    template <> inline bool MultiType::isType<char>()                 const { return (this->value_ && this->value_->type_ == MT_Type::Char);             } ///< Returns true if the current type equals the given type.
     504    template <> inline bool MultiType::isType<unsigned char>()        const { return (this->value_ && this->value_->type_ == MT_Type::UnsignedChar);     } ///< Returns true if the current type equals the given type.
     505    template <> inline bool MultiType::isType<short>()                const { return (this->value_ && this->value_->type_ == MT_Type::Short);            } ///< Returns true if the current type equals the given type.
     506    template <> inline bool MultiType::isType<unsigned short>()       const { return (this->value_ && this->value_->type_ == MT_Type::UnsignedShort);    } ///< Returns true if the current type equals the given type.
     507    template <> inline bool MultiType::isType<int>()                  const { return (this->value_ && this->value_->type_ == MT_Type::Int);              } ///< Returns true if the current type equals the given type.
     508    template <> inline bool MultiType::isType<unsigned int>()         const { return (this->value_ && this->value_->type_ == MT_Type::UnsignedInt);      } ///< Returns true if the current type equals the given type.
     509    template <> inline bool MultiType::isType<long>()                 const { return (this->value_ && this->value_->type_ == MT_Type::Long);             } ///< Returns true if the current type equals the given type.
     510    template <> inline bool MultiType::isType<unsigned long>()        const { return (this->value_ && this->value_->type_ == MT_Type::UnsignedLong);     } ///< Returns true if the current type equals the given type.
     511    template <> inline bool MultiType::isType<long long>()            const { return (this->value_ && this->value_->type_ == MT_Type::LongLong);         } ///< Returns true if the current type equals the given type.
     512    template <> inline bool MultiType::isType<unsigned long long>()   const { return (this->value_ && this->value_->type_ == MT_Type::UnsignedLongLong); } ///< Returns true if the current type equals the given type.
     513    template <> inline bool MultiType::isType<float>()                const { return (this->value_ && this->value_->type_ == MT_Type::Float);            } ///< Returns true if the current type equals the given type.
     514    template <> inline bool MultiType::isType<double>()               const { return (this->value_ && this->value_->type_ == MT_Type::Double);           } ///< Returns true if the current type equals the given type.
     515    template <> inline bool MultiType::isType<long double>()          const { return (this->value_ && this->value_->type_ == MT_Type::LongDouble);       } ///< Returns true if the current type equals the given type.
     516    template <> inline bool MultiType::isType<bool>()                 const { return (this->value_ && this->value_->type_ == MT_Type::Bool);             } ///< Returns true if the current type equals the given type.
     517    template <> inline bool MultiType::isType<void*>()                const { return (this->value_ && this->value_->type_ == MT_Type::VoidPointer);      } ///< Returns true if the current type equals the given type.
     518    template <> inline bool MultiType::isType<std::string>()          const { return (this->value_ && this->value_->type_ == MT_Type::String);           } ///< Returns true if the current type equals the given type.
     519    template <> inline bool MultiType::isType<orxonox::Vector2>()     const { return (this->value_ && this->value_->type_ == MT_Type::Vector2);          } ///< Returns true if the current type equals the given type.
     520    template <> inline bool MultiType::isType<orxonox::Vector3>()     const { return (this->value_ && this->value_->type_ == MT_Type::Vector3);          } ///< Returns true if the current type equals the given type.
     521    template <> inline bool MultiType::isType<orxonox::Vector4>()     const { return (this->value_ && this->value_->type_ == MT_Type::Vector4);          } ///< Returns true if the current type equals the given type.
     522    template <> inline bool MultiType::isType<orxonox::ColourValue>() const { return (this->value_ && this->value_->type_ == MT_Type::ColourValue);      } ///< Returns true if the current type equals the given type.
     523    template <> inline bool MultiType::isType<orxonox::Quaternion>()  const { return (this->value_ && this->value_->type_ == MT_Type::Quaternion);       } ///< Returns true if the current type equals the given type.
     524    template <> inline bool MultiType::isType<orxonox::Radian>()      const { return (this->value_ && this->value_->type_ == MT_Type::Radian);           } ///< Returns true if the current type equals the given type.
     525    template <> inline bool MultiType::isType<orxonox::Degree>()      const { return (this->value_ && this->value_->type_ == MT_Type::Degree);           } ///< Returns true if the current type equals the given type.
     526
     527    /// Deletes the content, type becomes MT_Type::Null.
     528    template <> inline bool MultiType::convert<void>()                 { this->reset(); return true; }
    495529
    496530    // Specialization to avoid ambiguities with the conversion operator
    497     template <> inline bool MultiType::convert<std::string>()          { return this->setValue<std::string>         (this->operator std::string());          } /** @brief Converts the current value to the given type. */
    498     template <> inline bool MultiType::convert<orxonox::Vector2>()     { return this->setValue<orxonox::Vector2>    (this->operator orxonox::Vector2());     } /** @brief Converts the current value to the given type. */
    499     template <> inline bool MultiType::convert<orxonox::Vector3>()     { return this->setValue<orxonox::Vector3>    (this->operator orxonox::Vector3());     } /** @brief Converts the current value to the given type. */
    500     template <> inline bool MultiType::convert<orxonox::Vector4>()     { return this->setValue<orxonox::Vector4>    (this->operator orxonox::Vector4());     } /** @brief Converts the current value to the given type. */
    501     template <> inline bool MultiType::convert<orxonox::ColourValue>() { return this->setValue<orxonox::ColourValue>(this->operator orxonox::ColourValue()); } /** @brief Converts the current value to the given type. */
    502     template <> inline bool MultiType::convert<orxonox::Quaternion>()  { return this->setValue<orxonox::Quaternion> (this->operator orxonox::Quaternion());  } /** @brief Converts the current value to the given type. */
    503     template <> inline bool MultiType::convert<orxonox::Radian>()      { return this->setValue<orxonox::Radian>     (this->operator orxonox::Radian());      } /** @brief Converts the current value to the given type. */
    504     template <> inline bool MultiType::convert<orxonox::Degree>()      { return this->setValue<orxonox::Degree>     (this->operator orxonox::Degree());      } /** @brief Converts the current value to the given type. */
     531    template <> inline bool MultiType::convert<std::string>()          { return this->setValue<std::string>         (this->operator std::string());          } ///< Converts the current value to the given type.
     532    template <> inline bool MultiType::convert<orxonox::Vector2>()     { return this->setValue<orxonox::Vector2>    (this->operator orxonox::Vector2());     } ///< Converts the current value to the given type.
     533    template <> inline bool MultiType::convert<orxonox::Vector3>()     { return this->setValue<orxonox::Vector3>    (this->operator orxonox::Vector3());     } ///< Converts the current value to the given type.
     534    template <> inline bool MultiType::convert<orxonox::Vector4>()     { return this->setValue<orxonox::Vector4>    (this->operator orxonox::Vector4());     } ///< Converts the current value to the given type.
     535    template <> inline bool MultiType::convert<orxonox::ColourValue>() { return this->setValue<orxonox::ColourValue>(this->operator orxonox::ColourValue()); } ///< Converts the current value to the given type.
     536    template <> inline bool MultiType::convert<orxonox::Quaternion>()  { return this->setValue<orxonox::Quaternion> (this->operator orxonox::Quaternion());  } ///< Converts the current value to the given type.
     537    template <> inline bool MultiType::convert<orxonox::Radian>()      { return this->setValue<orxonox::Radian>     (this->operator orxonox::Radian());      } ///< Converts the current value to the given type.
     538    template <> inline bool MultiType::convert<orxonox::Degree>()      { return this->setValue<orxonox::Degree>     (this->operator orxonox::Degree());      } ///< Converts the current value to the given type.
    505539
    506540    // Specialization to avoid ambiguities with the conversion operator
    507     template <> inline bool MultiType::convert<const std::string&>()          { return this->convert<std::string>();          } /** @brief Converts the current value to the given type. */
    508     template <> inline bool MultiType::convert<const orxonox::Vector2&>()     { return this->convert<orxonox::Vector2>();     } /** @brief Converts the current value to the given type. */
    509     template <> inline bool MultiType::convert<const orxonox::Vector3&>()     { return this->convert<orxonox::Vector3>();     } /** @brief Converts the current value to the given type. */
    510     template <> inline bool MultiType::convert<const orxonox::Vector4&>()     { return this->convert<orxonox::Vector4>();     } /** @brief Converts the current value to the given type. */
    511     template <> inline bool MultiType::convert<const orxonox::ColourValue&>() { return this->convert<orxonox::ColourValue>(); } /** @brief Converts the current value to the given type. */
    512     template <> inline bool MultiType::convert<const orxonox::Quaternion&>()  { return this->convert<orxonox::Quaternion>();  } /** @brief Converts the current value to the given type. */
    513     template <> inline bool MultiType::convert<const orxonox::Radian&>()      { return this->convert<orxonox::Radian>();      } /** @brief Converts the current value to the given type. */
    514     template <> inline bool MultiType::convert<const orxonox::Degree&>()      { return this->convert<orxonox::Degree>();      } /** @brief Converts the current value to the given type. */
     541    template <> inline bool MultiType::convert<const std::string&>()          { return this->convert<std::string>();          } ///< Converts the current value to the given type.
     542    template <> inline bool MultiType::convert<const orxonox::Vector2&>()     { return this->convert<orxonox::Vector2>();     } ///< Converts the current value to the given type.
     543    template <> inline bool MultiType::convert<const orxonox::Vector3&>()     { return this->convert<orxonox::Vector3>();     } ///< Converts the current value to the given type.
     544    template <> inline bool MultiType::convert<const orxonox::Vector4&>()     { return this->convert<orxonox::Vector4>();     } ///< Converts the current value to the given type.
     545    template <> inline bool MultiType::convert<const orxonox::ColourValue&>() { return this->convert<orxonox::ColourValue>(); } ///< Converts the current value to the given type.
     546    template <> inline bool MultiType::convert<const orxonox::Quaternion&>()  { return this->convert<orxonox::Quaternion>();  } ///< Converts the current value to the given type.
     547    template <> inline bool MultiType::convert<const orxonox::Radian&>()      { return this->convert<orxonox::Radian>();      } ///< Converts the current value to the given type.
     548    template <> inline bool MultiType::convert<const orxonox::Degree&>()      { return this->convert<orxonox::Degree>();      } ///< Converts the current value to the given type.
    515549
    516550    template <> _UtilExport void MultiType::createNewValueContainer(const char& value);
    … …  
    538572    template <> _UtilExport void MultiType::createNewValueContainer(const orxonox::Degree& value);
    539573
    540     inline bool MultiType::setValue(const char& value)                  { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } /** @brief Assigns the given value and converts it to the current type. */
    541     inline bool MultiType::setValue(const unsigned char& value)         { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } /** @brief Assigns the given value and converts it to the current type. */
    542     inline bool MultiType::setValue(const short& value)                 { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } /** @brief Assigns the given value and converts it to the current type. */
    543     inline bool MultiType::setValue(const unsigned short& value)        { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } /** @brief Assigns the given value and converts it to the current type. */
    544     inline bool MultiType::setValue(const int& value)                   { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } /** @brief Assigns the given value and converts it to the current type. */
    545     inline bool MultiType::setValue(const unsigned int& value)          { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } /** @brief Assigns the given value and converts it to the current type. */
    546     inline bool MultiType::setValue(const long& value)                  { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } /** @brief Assigns the given value and converts it to the current type. */
    547     inline bool MultiType::setValue(const unsigned long& value)         { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } /** @brief Assigns the given value and converts it to the current type. */
    548     inline bool MultiType::setValue(const long long& value)             { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } /** @brief Assigns the given value and converts it to the current type. */
    549     inline bool MultiType::setValue(const unsigned long long& value)    { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } /** @brief Assigns the given value and converts it to the current type. */
    550     inline bool MultiType::setValue(const float& value)                 { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } /** @brief Assigns the given value and converts it to the current type. */
    551     inline bool MultiType::setValue(const double& value)                { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } /** @brief Assigns the given value and converts it to the current type. */
    552     inline bool MultiType::setValue(const long double& value)           { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } /** @brief Assigns the given value and converts it to the current type. */
    553     inline bool MultiType::setValue(const bool& value)                  { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } /** @brief Assigns the given value and converts it to the current type. */
    554     inline bool MultiType::setValue(      void* const& value)           { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } /** @brief Assigns the given value and converts it to the current type. */
    555     inline bool MultiType::setValue(const std::string& value)           { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } /** @brief Assigns the given value and converts it to the current type. */
    556     inline bool MultiType::setValue(const orxonox::Vector2& value)      { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } /** @brief Assigns the given value and converts it to the current type. */
    557     inline bool MultiType::setValue(const orxonox::Vector3& value)      { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } /** @brief Assigns the given value and converts it to the current type. */
    558     inline bool MultiType::setValue(const orxonox::Vector4& value)      { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } /** @brief Assigns the given value and converts it to the current type. */
    559     inline bool MultiType::setValue(const orxonox::ColourValue& value)  { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } /** @brief Assigns the given value and converts it to the current type. */
    560     inline bool MultiType::setValue(const orxonox::Quaternion& value)   { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } /** @brief Assigns the given value and converts it to the current type. */
    561     inline bool MultiType::setValue(const orxonox::Radian& value)       { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } /** @brief Assigns the given value and converts it to the current type. */
    562     inline bool MultiType::setValue(const orxonox::Degree& value)       { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } /** @brief Assigns the given value and converts it to the current type. */
    563 
    564     inline bool MultiType::setValue(const char* value)                  { if (this->value_) { return this->value_->setValue(std::string(value)); } else { return this->assignValue(std::string(value)); } }  /** @brief Assigns the given value and converts it to the current type. */
     574    inline bool MultiType::setValue(const char& value)                  { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } ///< Assigns the given value and converts it to the current type.
     575    inline bool MultiType::setValue(const unsigned char& value)         { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } ///< Assigns the given value and converts it to the current type.
     576    inline bool MultiType::setValue(const short& value)                 { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } ///< Assigns the given value and converts it to the current type.
     577    inline bool MultiType::setValue(const unsigned short& value)        { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } ///< Assigns the given value and converts it to the current type.
     578    inline bool MultiType::setValue(const int& value)                   { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } ///< Assigns the given value and converts it to the current type.
     579    inline bool MultiType::setValue(const unsigned int& value)          { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } ///< Assigns the given value and converts it to the current type.
     580    inline bool MultiType::setValue(const long& value)                  { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } ///< Assigns the given value and converts it to the current type.
     581    inline bool MultiType::setValue(const unsigned long& value)         { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } ///< Assigns the given value and converts it to the current type.
     582    inline bool MultiType::setValue(const long long& value)             { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } ///< Assigns the given value and converts it to the current type.
     583    inline bool MultiType::setValue(const unsigned long long& value)    { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } ///< Assigns the given value and converts it to the current type.
     584    inline bool MultiType::setValue(const float& value)                 { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } ///< Assigns the given value and converts it to the current type.
     585    inline bool MultiType::setValue(const double& value)                { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } ///< Assigns the given value and converts it to the current type.
     586    inline bool MultiType::setValue(const long double& value)           { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } ///< Assigns the given value and converts it to the current type.
     587    inline bool MultiType::setValue(const bool& value)                  { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } ///< Assigns the given value and converts it to the current type.
     588    inline bool MultiType::setValue(      void* const& value)           { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } ///< Assigns the given value and converts it to the current type.
     589    inline bool MultiType::setValue(const std::string& value)           { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } ///< Assigns the given value and converts it to the current type.
     590    inline bool MultiType::setValue(const orxonox::Vector2& value)      { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } ///< Assigns the given value and converts it to the current type.
     591    inline bool MultiType::setValue(const orxonox::Vector3& value)      { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } ///< Assigns the given value and converts it to the current type.
     592    inline bool MultiType::setValue(const orxonox::Vector4& value)      { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } ///< Assigns the given value and converts it to the current type.
     593    inline bool MultiType::setValue(const orxonox::ColourValue& value)  { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } ///< Assigns the given value and converts it to the current type.
     594    inline bool MultiType::setValue(const orxonox::Quaternion& value)   { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } ///< Assigns the given value and converts it to the current type.
     595    inline bool MultiType::setValue(const orxonox::Radian& value)       { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } ///< Assigns the given value and converts it to the current type.
     596    inline bool MultiType::setValue(const orxonox::Degree& value)       { if (this->value_) { return this->value_->setValue(value); } else { return this->assignValue(value); } } ///< Assigns the given value and converts it to the current type.
     597
     598    /// Assigns the given value and converts it to the current type.
     599    inline bool MultiType::setValue(const char* value)                  { if (this->value_) { return this->value_->setValue(std::string(value)); } else { return this->assignValue(std::string(value)); } }
    565600}
    566601

  • code/trunk/src/libraries/util/MultiTypeValue.h

    r6417 r7401  
    2929/**
    3030    @file
     31    @ingroup MultiType
    3132    @brief Declaration and Implementation of the MT_Value<T> class.
    3233
    … …  
    5354    {
    5455    public:
    55         /** @brief Constructor: Assigns the value and the type identifier. */
     56        /// Constructor: Assigns the value and the type identifier.
    5657        MT_Value(const T& value, MT_Type::Value type) : MT_ValueBase(type), value_(value) {}
    5758
    58         /** @brief Creates a copy of itself. */
     59        /// Creates a copy of itself.
    5960        inline MT_ValueBase* clone() const { return new MT_Value<T>(this->value_, this->type_); }
    6061
    61         /** @brief Resets the current value to the default. */
     62        /// Resets the current value to the default.
    6263        inline void reset() { this->value_ = zeroise<T>(); bHasDefaultValue_ = true; }
    6364
    64         /** @brief Assigns the value of the other MultiType, converted to T. @param other The other MultiType */
     65        /**
     66            @brief Assigns the value of the other MultiType, converted to T.
     67            @param other The other MultiType
     68        */
    6569        inline bool assimilate(const MultiType& other)
    6670        {
    … …  
    7680        }
    7781
    78         inline bool getValue(char*                 value) const { return convertValue<T, char                >(value, value_, 0); } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    79         inline bool getValue(unsigned char*        value) const { return convertValue<T, unsigned char       >(value, value_, 0); } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    80         inline bool getValue(short*                value) const { return convertValue<T, short               >(value, value_, 0); } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    81         inline bool getValue(unsigned short*       value) const { return convertValue<T, unsigned short      >(value, value_, 0); } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    82         inline bool getValue(int*                  value) const { return convertValue<T, int                 >(value, value_, 0); } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    83         inline bool getValue(unsigned int*         value) const { return convertValue<T, unsigned int        >(value, value_, 0); } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    84         inline bool getValue(long*                 value) const { return convertValue<T, long                >(value, value_, 0); } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    85         inline bool getValue(unsigned long*        value) const { return convertValue<T, unsigned long       >(value, value_, 0); } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    86         inline bool getValue(long long*            value) const { return convertValue<T, long long           >(value, value_, 0); } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    87         inline bool getValue(unsigned long long*   value) const { return convertValue<T, unsigned long long  >(value, value_, 0); } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    88         inline bool getValue(float*                value) const { return convertValue<T, float               >(value, value_, 0); } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    89         inline bool getValue(double*               value) const { return convertValue<T, double              >(value, value_, 0); } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    90         inline bool getValue(long double*          value) const { return convertValue<T, long double         >(value, value_, 0); } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    91         inline bool getValue(bool*                 value) const { return convertValue<T, bool                >(value, value_, 0); } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    92         inline bool getValue(void**                value) const { return convertValue<T, void*               >(value, value_, 0); } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    93         inline bool getValue(std::string*          value) const { return convertValue<T, std::string         >(value, value_, zeroise<std::string>         ()); } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    94         inline bool getValue(orxonox::Vector2*     value) const { return convertValue<T, orxonox::Vector2    >(value, value_, zeroise<orxonox::Vector2>    ()); } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    95         inline bool getValue(orxonox::Vector3*     value) const { return convertValue<T, orxonox::Vector3    >(value, value_, zeroise<orxonox::Vector3>    ()); } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    96         inline bool getValue(orxonox::Vector4*     value) const { return convertValue<T, orxonox::Vector4    >(value, value_, zeroise<orxonox::Vector4>    ()); } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    97         inline bool getValue(orxonox::ColourValue* value) const { return convertValue<T, orxonox::ColourValue>(value, value_, zeroise<orxonox::ColourValue>()); } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    98         inline bool getValue(orxonox::Quaternion*  value) const { return convertValue<T, orxonox::Quaternion >(value, value_, zeroise<orxonox::Quaternion> ()); } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    99         inline bool getValue(orxonox::Radian*      value) const { return convertValue<T, orxonox::Radian     >(value, value_, zeroise<orxonox::Radian>     ()); } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    100         inline bool getValue(orxonox::Degree*      value) const { return convertValue<T, orxonox::Degree     >(value, value_, zeroise<orxonox::Degree>     ()); } /** @brief Assigns the value to the given pointer. The value gets converted if the types don't match. */
    101 
    102         inline bool setValue(const char& value)                 { return !(bHasDefaultValue_ = !convertValue<char                , T>(&value_, value, zeroise<T>())); } /** @brief Assigns the value by converting it to T. */
    103         inline bool setValue(const unsigned char& value)        { return !(bHasDefaultValue_ = !convertValue<unsigned char       , T>(&value_, value, zeroise<T>())); } /** @brief Assigns the value by converting it to T. */
    104         inline bool setValue(const short& value)                { return !(bHasDefaultValue_ = !convertValue<short               , T>(&value_, value, zeroise<T>())); } /** @brief Assigns the value by converting it to T. */
    105         inline bool setValue(const unsigned short& value)       { return !(bHasDefaultValue_ = !convertValue<unsigned short      , T>(&value_, value, zeroise<T>())); } /** @brief Assigns the value by converting it to T. */
    106         inline bool setValue(const int& value)                  { return !(bHasDefaultValue_ = !convertValue<int                 , T>(&value_, value, zeroise<T>())); } /** @brief Assigns the value by converting it to T. */
    107         inline bool setValue(const unsigned int& value)         { return !(bHasDefaultValue_ = !convertValue<unsigned int        , T>(&value_, value, zeroise<T>())); } /** @brief Assigns the value by converting it to T. */
    108         inline bool setValue(const long& value)                 { return !(bHasDefaultValue_ = !convertValue<long                , T>(&value_, value, zeroise<T>())); } /** @brief Assigns the value by converting it to T. */
    109         inline bool setValue(const unsigned long& value)        { return !(bHasDefaultValue_ = !convertValue<unsigned long       , T>(&value_, value, zeroise<T>())); } /** @brief Assigns the value by converting it to T. */
    110         inline bool setValue(const long long& value)            { return !(bHasDefaultValue_ = !convertValue<long long           , T>(&value_, value, zeroise<T>())); } /** @brief Assigns the value by converting it to T. */
    111         inline bool setValue(const unsigned long long& value)   { return !(bHasDefaultValue_ = !convertValue<unsigned long long  , T>(&value_, value, zeroise<T>())); } /** @brief Assigns the value by converting it to T. */
    112         inline bool setValue(const float& value)                { return !(bHasDefaultValue_ = !convertValue<float               , T>(&value_, value, zeroise<T>())); } /** @brief Assigns the value by converting it to T. */
    113         inline bool setValue(const double& value)               { return !(bHasDefaultValue_ = !convertValue<double              , T>(&value_, value, zeroise<T>())); } /** @brief Assigns the value by converting it to T. */
    114         inline bool setValue(const long double& value)          { return !(bHasDefaultValue_ = !convertValue<long double         , T>(&value_, value, zeroise<T>())); } /** @brief Assigns the value by converting it to T. */
    115         inline bool setValue(const bool& value)                 { return !(bHasDefaultValue_ = !convertValue<bool                , T>(&value_, value, zeroise<T>())); } /** @brief Assigns the value by converting it to T. */
    116         inline bool setValue(      void* const& value)          { return !(bHasDefaultValue_ = !convertValue<void*               , T>(&value_, value, zeroise<T>())); } /** @brief Assigns the value by converting it to T. */
    117         inline bool setValue(const std::string& value)          { return !(bHasDefaultValue_ = !convertValue<std::string         , T>(&value_, value, zeroise<T>())); } /** @brief Assigns the value by converting it to T. */
    118         inline bool setValue(const orxonox::Vector2& value)     { return !(bHasDefaultValue_ = !convertValue<orxonox::Vector2    , T>(&value_, value, zeroise<T>())); } /** @brief Assigns the value by converting it to T. */
    119         inline bool setValue(const orxonox::Vector3& value)     { return !(bHasDefaultValue_ = !convertValue<orxonox::Vector3    , T>(&value_, value, zeroise<T>())); } /** @brief Assigns the value by converting it to T. */
    120         inline bool setValue(const orxonox::Vector4& value)     { return !(bHasDefaultValue_ = !convertValue<orxonox::Vector4    , T>(&value_, value, zeroise<T>())); } /** @brief Assigns the value by converting it to T. */
    121         inline bool setValue(const orxonox::ColourValue& value) { return !(bHasDefaultValue_ = !convertValue<orxonox::ColourValue, T>(&value_, value, zeroise<T>())); } /** @brief Assigns the value by converting it to T. */
    122         inline bool setValue(const orxonox::Quaternion& value)  { return !(bHasDefaultValue_ = !convertValue<orxonox::Quaternion , T>(&value_, value, zeroise<T>())); } /** @brief Assigns the value by converting it to T. */
    123         inline bool setValue(const orxonox::Radian& value)      { return !(bHasDefaultValue_ = !convertValue<orxonox::Radian     , T>(&value_, value, zeroise<T>())); } /** @brief Assigns the value by converting it to T. */
    124         inline bool setValue(const orxonox::Degree& value)      { return !(bHasDefaultValue_ = !convertValue<orxonox::Degree     , T>(&value_, value, zeroise<T>())); } /** @brief Assigns the value by converting it to T. */
    125 
    126         inline operator char()                 const { return getConvertedValue<T, char>                (this->value_, 0); }     /** @brief Returns the current value, converted to the requested type. */
    127         inline operator unsigned char()        const { return getConvertedValue<T, unsigned char>       (this->value_, 0); }     /** @brief Returns the current value, converted to the requested type. */
    128         inline operator short()                const { return getConvertedValue<T, short>               (this->value_, 0); }     /** @brief Returns the current value, converted to the requested type. */
    129         inline operator unsigned short()       const { return getConvertedValue<T, unsigned short>      (this->value_, 0); }     /** @brief Returns the current value, converted to the requested type. */
    130         inline operator int()                  const { return getConvertedValue<T, int>                 (this->value_, 0); }     /** @brief Returns the current value, converted to the requested type. */
    131         inline operator unsigned int()         const { return getConvertedValue<T, unsigned int>        (this->value_, 0); }     /** @brief Returns the current value, converted to the requested type. */
    132         inline operator long()                 const { return getConvertedValue<T, long>                (this->value_, 0); }     /** @brief Returns the current value, converted to the requested type. */
    133         inline operator unsigned long()        const { return getConvertedValue<T, unsigned long>       (this->value_, 0); }     /** @brief Returns the current value, converted to the requested type. */
    134         inline operator long long()            const { return getConvertedValue<T, long long>           (this->value_, 0); }     /** @brief Returns the current value, converted to the requested type. */
    135         inline operator unsigned long long()   const { return getConvertedValue<T, unsigned long long>  (this->value_, 0); }     /** @brief Returns the current value, converted to the requested type. */
    136         inline operator float()                const { return getConvertedValue<T, float>               (this->value_, 0); }     /** @brief Returns the current value, converted to the requested type. */
    137         inline operator double()               const { return getConvertedValue<T, double>              (this->value_, 0); }     /** @brief Returns the current value, converted to the requested type. */
    138         inline operator long double()          const { return getConvertedValue<T, long double>         (this->value_, 0); }     /** @brief Returns the current value, converted to the requested type. */
    139         inline operator bool()                 const { return getConvertedValue<T, bool>                (this->value_, 0); }     /** @brief Returns the current value, converted to the requested type. */
    140         inline operator void*()                const { return getConvertedValue<T, void*>               (this->value_, 0); }     /** @brief Returns the current value, converted to the requested type. */
    141         inline operator std::string()          const { return getConvertedValue<T, std::string>         (this->value_, NilValue<std::string         >()); } /** @brief Returns the current value, converted to the requested type. */
    142         inline operator orxonox::Vector2()     const { return getConvertedValue<T, orxonox::Vector2>    (this->value_, NilValue<orxonox::Vector2    >()); } /** @brief Returns the current value, converted to the requested type. */
    143         inline operator orxonox::Vector3()     const { return getConvertedValue<T, orxonox::Vector3>    (this->value_, NilValue<orxonox::Vector3    >()); } /** @brief Returns the current value, converted to the requested type. */
    144         inline operator orxonox::Vector4()     const { return getConvertedValue<T, orxonox::Vector4>    (this->value_, NilValue<orxonox::Vector4    >()); } /** @brief Returns the current value, converted to the requested type. */
    145         inline operator orxonox::ColourValue() const { return getConvertedValue<T, orxonox::ColourValue>(this->value_, NilValue<orxonox::ColourValue>()); } /** @brief Returns the current value, converted to the requested type. */
    146         inline operator orxonox::Quaternion()  const { return getConvertedValue<T, orxonox::Quaternion> (this->value_, NilValue<orxonox::Quaternion >()); } /** @brief Returns the current value, converted to the requested type. */
    147         inline operator orxonox::Radian()      const { return getConvertedValue<T, orxonox::Radian>     (this->value_, NilValue<orxonox::Radian     >()); } /** @brief Returns the current value, converted to the requested type. */
    148         inline operator orxonox::Degree()      const { return getConvertedValue<T, orxonox::Degree>     (this->value_, NilValue<orxonox::Degree     >()); } /** @brief Returns the current value, converted to the requested type. */
    149 
    150         /** @brief Puts the current value on the stream */
     82        inline bool getValue(char*                 value) const { return convertValue<T, char                >(value, value_, 0); } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     83        inline bool getValue(unsigned char*        value) const { return convertValue<T, unsigned char       >(value, value_, 0); } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     84        inline bool getValue(short*                value) const { return convertValue<T, short               >(value, value_, 0); } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     85        inline bool getValue(unsigned short*       value) const { return convertValue<T, unsigned short      >(value, value_, 0); } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     86        inline bool getValue(int*                  value) const { return convertValue<T, int                 >(value, value_, 0); } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     87        inline bool getValue(unsigned int*         value) const { return convertValue<T, unsigned int        >(value, value_, 0); } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     88        inline bool getValue(long*                 value) const { return convertValue<T, long                >(value, value_, 0); } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     89        inline bool getValue(unsigned long*        value) const { return convertValue<T, unsigned long       >(value, value_, 0); } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     90        inline bool getValue(long long*            value) const { return convertValue<T, long long           >(value, value_, 0); } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     91        inline bool getValue(unsigned long long*   value) const { return convertValue<T, unsigned long long  >(value, value_, 0); } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     92        inline bool getValue(float*                value) const { return convertValue<T, float               >(value, value_, 0); } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     93        inline bool getValue(double*               value) const { return convertValue<T, double              >(value, value_, 0); } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     94        inline bool getValue(long double*          value) const { return convertValue<T, long double         >(value, value_, 0); } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     95        inline bool getValue(bool*                 value) const { return convertValue<T, bool                >(value, value_, 0); } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     96        inline bool getValue(void**                value) const { return convertValue<T, void*               >(value, value_, 0); } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     97        inline bool getValue(std::string*          value) const { return convertValue<T, std::string         >(value, value_, zeroise<std::string>         ()); } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     98        inline bool getValue(orxonox::Vector2*     value) const { return convertValue<T, orxonox::Vector2    >(value, value_, zeroise<orxonox::Vector2>    ()); } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     99        inline bool getValue(orxonox::Vector3*     value) const { return convertValue<T, orxonox::Vector3    >(value, value_, zeroise<orxonox::Vector3>    ()); } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     100        inline bool getValue(orxonox::Vector4*     value) const { return convertValue<T, orxonox::Vector4    >(value, value_, zeroise<orxonox::Vector4>    ()); } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     101        inline bool getValue(orxonox::ColourValue* value) const { return convertValue<T, orxonox::ColourValue>(value, value_, zeroise<orxonox::ColourValue>()); } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     102        inline bool getValue(orxonox::Quaternion*  value) const { return convertValue<T, orxonox::Quaternion >(value, value_, zeroise<orxonox::Quaternion> ()); } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     103        inline bool getValue(orxonox::Radian*      value) const { return convertValue<T, orxonox::Radian     >(value, value_, zeroise<orxonox::Radian>     ()); } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     104        inline bool getValue(orxonox::Degree*      value) const { return convertValue<T, orxonox::Degree     >(value, value_, zeroise<orxonox::Degree>     ()); } ///< Assigns the value to the given pointer. The value gets converted if the types don't match.
     105
     106        inline bool setValue(const char& value)                 { return !(bHasDefaultValue_ = !convertValue<char                , T>(&value_, value, zeroise<T>())); } ///< Assigns the value by converting it to T.
     107        inline bool setValue(const unsigned char& value)        { return !(bHasDefaultValue_ = !convertValue<unsigned char       , T>(&value_, value, zeroise<T>())); } ///< Assigns the value by converting it to T.
     108        inline bool setValue(const short& value)                { return !(bHasDefaultValue_ = !convertValue<short               , T>(&value_, value, zeroise<T>())); } ///< Assigns the value by converting it to T.
     109        inline bool setValue(const unsigned short& value)       { return !(bHasDefaultValue_ = !convertValue<unsigned short      , T>(&value_, value, zeroise<T>())); } ///< Assigns the value by converting it to T.
     110        inline bool setValue(const int& value)                  { return !(bHasDefaultValue_ = !convertValue<int                 , T>(&value_, value, zeroise<T>())); } ///< Assigns the value by converting it to T.
     111        inline bool setValue(const unsigned int& value)         { return !(bHasDefaultValue_ = !convertValue<unsigned int        , T>(&value_, value, zeroise<T>())); } ///< Assigns the value by converting it to T.
     112        inline bool setValue(const long& value)                 { return !(bHasDefaultValue_ = !convertValue<long                , T>(&value_, value, zeroise<T>())); } ///< Assigns the value by converting it to T.
     113        inline bool setValue(const unsigned long& value)        { return !(bHasDefaultValue_ = !convertValue<unsigned long       , T>(&value_, value, zeroise<T>())); } ///< Assigns the value by converting it to T.
     114        inline bool setValue(const long long& value)            { return !(bHasDefaultValue_ = !convertValue<long long           , T>(&value_, value, zeroise<T>())); } ///< Assigns the value by converting it to T.
     115        inline bool setValue(const unsigned long long& value)   { return !(bHasDefaultValue_ = !convertValue<unsigned long long  , T>(&value_, value, zeroise<T>())); } ///< Assigns the value by converting it to T.
     116        inline bool setValue(const float& value)                { return !(bHasDefaultValue_ = !convertValue<float               , T>(&value_, value, zeroise<T>())); } ///< Assigns the value by converting it to T.
     117        inline bool setValue(const double& value)               { return !(bHasDefaultValue_ = !convertValue<double              , T>(&value_, value, zeroise<T>())); } ///< Assigns the value by converting it to T.
     118        inline bool setValue(const long double& value)          { return !(bHasDefaultValue_ = !convertValue<long double         , T>(&value_, value, zeroise<T>())); } ///< Assigns the value by converting it to T.
     119        inline bool setValue(const bool& value)                 { return !(bHasDefaultValue_ = !convertValue<bool                , T>(&value_, value, zeroise<T>())); } ///< Assigns the value by converting it to T.
     120        inline bool setValue(      void* const& value)          { return !(bHasDefaultValue_ = !convertValue<void*               , T>(&value_, value, zeroise<T>())); } ///< Assigns the value by converting it to T.
     121        inline bool setValue(const std::string& value)          { return !(bHasDefaultValue_ = !convertValue<std::string         , T>(&value_, value, zeroise<T>())); } ///< Assigns the value by converting it to T.
     122        inline bool setValue(const orxonox::Vector2& value)     { return !(bHasDefaultValue_ = !convertValue<orxonox::Vector2    , T>(&value_, value, zeroise<T>())); } ///< Assigns the value by converting it to T.
     123        inline bool setValue(const orxonox::Vector3& value)     { return !(bHasDefaultValue_ = !convertValue<orxonox::Vector3    , T>(&value_, value, zeroise<T>())); } ///< Assigns the value by converting it to T.
     124        inline bool setValue(const orxonox::Vector4& value)     { return !(bHasDefaultValue_ = !convertValue<orxonox::Vector4    , T>(&value_, value, zeroise<T>())); } ///< Assigns the value by converting it to T.
     125        inline bool setValue(const orxonox::ColourValue& value) { return !(bHasDefaultValue_ = !convertValue<orxonox::ColourValue, T>(&value_, value, zeroise<T>())); } ///< Assigns the value by converting it to T.
     126        inline bool setValue(const orxonox::Quaternion& value)  { return !(bHasDefaultValue_ = !convertValue<orxonox::Quaternion , T>(&value_, value, zeroise<T>())); } ///< Assigns the value by converting it to T.
     127        inline bool setValue(const orxonox::Radian& value)      { return !(bHasDefaultValue_ = !convertValue<orxonox::Radian     , T>(&value_, value, zeroise<T>())); } ///< Assigns the value by converting it to T.
     128        inline bool setValue(const orxonox::Degree& value)      { return !(bHasDefaultValue_ = !convertValue<orxonox::Degree     , T>(&value_, value, zeroise<T>())); } ///< Assigns the value by converting it to T.
     129
     130        inline operator char()                 const { return getConvertedValue<T, char>                (this->value_, 0); }     ///< Returns the current value, converted to the requested type.
     131        inline operator unsigned char()        const { return getConvertedValue<T, unsigned char>       (this->value_, 0); }     ///< Returns the current value, converted to the requested type.
     132        inline operator short()                const { return getConvertedValue<T, short>               (this->value_, 0); }     ///< Returns the current value, converted to the requested type.
     133        inline operator unsigned short()       const { return getConvertedValue<T, unsigned short>      (this->value_, 0); }     ///< Returns the current value, converted to the requested type.
     134        inline operator int()                  const { return getConvertedValue<T, int>                 (this->value_, 0); }     ///< Returns the current value, converted to the requested type.
     135        inline operator unsigned int()         const { return getConvertedValue<T, unsigned int>        (this->value_, 0); }     ///< Returns the current value, converted to the requested type.
     136        inline operator long()                 const { return getConvertedValue<T, long>                (this->value_, 0); }     ///< Returns the current value, converted to the requested type.
     137        inline operator unsigned long()        const { return getConvertedValue<T, unsigned long>       (this->value_, 0); }     ///< Returns the current value, converted to the requested type.
     138        inline operator long long()            const { return getConvertedValue<T, long long>           (this->value_, 0); }     ///< Returns the current value, converted to the requested type.
     139        inline operator unsigned long long()   const { return getConvertedValue<T, unsigned long long>  (this->value_, 0); }     ///< Returns the current value, converted to the requested type.
     140        inline operator float()                const { return getConvertedValue<T, float>               (this->value_, 0); }     ///< Returns the current value, converted to the requested type.
     141        inline operator double()               const { return getConvertedValue<T, double>              (this->value_, 0); }     ///< Returns the current value, converted to the requested type.
     142        inline operator long double()          const { return getConvertedValue<T, long double>         (this->value_, 0); }     ///< Returns the current value, converted to the requested type.
     143        inline operator bool()                 const { return getConvertedValue<T, bool>                (this->value_, 0); }     ///< Returns the current value, converted to the requested type.
     144        inline operator void*()                const { return getConvertedValue<T, void*>               (this->value_, 0); }     ///< Returns the current value, converted to the requested type.
     145        inline operator std::string()          const { return getConvertedValue<T, std::string>         (this->value_, NilValue<std::string         >()); } ///< Returns the current value, converted to the requested type.
     146        inline operator orxonox::Vector2()     const { return getConvertedValue<T, orxonox::Vector2>    (this->value_, NilValue<orxonox::Vector2    >()); } ///< Returns the current value, converted to the requested type.
     147        inline operator orxonox::Vector3()     const { return getConvertedValue<T, orxonox::Vector3>    (this->value_, NilValue<orxonox::Vector3    >()); } ///< Returns the current value, converted to the requested type.
     148        inline operator orxonox::Vector4()     const { return getConvertedValue<T, orxonox::Vector4>    (this->value_, NilValue<orxonox::Vector4    >()); } ///< Returns the current value, converted to the requested type.
     149        inline operator orxonox::ColourValue() const { return getConvertedValue<T, orxonox::ColourValue>(this->value_, NilValue<orxonox::ColourValue>()); } ///< Returns the current value, converted to the requested type.
     150        inline operator orxonox::Quaternion()  const { return getConvertedValue<T, orxonox::Quaternion> (this->value_, NilValue<orxonox::Quaternion >()); } ///< Returns the current value, converted to the requested type.
     151        inline operator orxonox::Radian()      const { return getConvertedValue<T, orxonox::Radian>     (this->value_, NilValue<orxonox::Radian     >()); } ///< Returns the current value, converted to the requested type.
     152        inline operator orxonox::Degree()      const { return getConvertedValue<T, orxonox::Degree>     (this->value_, NilValue<orxonox::Degree     >()); } ///< Returns the current value, converted to the requested type.
     153
     154        /// Puts the current value on the stream
    151155        inline void toString(std::ostream& outstream) const { outstream << this->value_; }
    152156
    153         /** @brief loads data from the bytestream (mem) into the MT and increases the bytestream pointer by the size of the data */
     157        /// loads data from the bytestream (mem) into the MT and increases the bytestream pointer by the size of the data
    154158        inline void importData( uint8_t*& mem )         { loadAndIncrease( /*(const T&)*/this->value_, mem ); }
    155         /** @brief saves data from the MT into the bytestream (mem) and increases the bytestream pointer by the size of the data */
     159        /// saves data from the MT into the bytestream (mem) and increases the bytestream pointer by the size of the data
    156160        inline void exportData( uint8_t*& mem ) const   { saveAndIncrease( /*(const T&)*/this->value_, mem ); }
    157         /** @brief returns the size of the data that would be saved by exportData */
     161        /// returns the size of the data that would be saved by exportData
    158162        inline uint8_t getSize() const { return returnSize( this->value_ ); }
    159163
    160         T value_; //!< The stored value
     164        T value_; ///< The stored value
    161165    };
    162166

  • code/trunk/src/libraries/util/OrxAssert.h

    r6105 r7401  
    2929/**
    3030@file
     31@ingroup ExceptionAssertion
    3132@brief
    3233    Declaration of custom assertion facilities
    … …  
    4142#include "OutputHandler.h"
    4243
    43 // define an assert macro that can display a message
    4444#ifndef NDEBUG
     45/** Run time assertion like assert(), but with an embedded message.
     46@details
     47    The message will be printed as error with COUT(1). <br>
     48    You can use the same magic here as you can with \ref ThrowException
     49    @code
     50        OrxAssert(condition, "Text: " << number << " more text");
     51    @endcode
     52*/
    4553#define OrxAssert(Assertion, ErrorMessage) \
    4654    Assertion ? ((void)0) : (void)(orxonox::OutputHandler::getOutStream(1) << ErrorMessage << std::endl); \

  • code/trunk/src/libraries/util/OrxEnum.h

    r5738 r7401  
    2828
    2929/**
    30 @file
    31 @brief
    32     Declaration of the OrxEnum class.
     30    @file
     31    @ingroup Util
    3332*/
    3433
    … …  
    4039namespace orxonox
    4140{
     41    /** Lightweight enumeration class that can be extended at run time.
     42    @details
     43        The class accepts type int and also defines operator int(). Therefore
     44        int and OrxEnum can be used interchangeably so you can extend the content
     45        of the enumeration at run time by adding ints.
     46    @par Declaring an OrxEnum
     47        Write a struct that inherits OrxEnum and use some macros:
     48        @code
     49        struct MyEnum : OrxEnum<MyEnum>
     50        {
     51            OrxEnumConstructors(MyEnum);
     52
     53            static const int Value1 = -1;
     54            static const int Value2 = 0;
     55            static const int Value3 = Value2 + 10;
     56        };
     57        @endcode
     58    */
    4259    template <class T>
    4360    struct OrxEnum
    … …  
    4562        public:
    4663            OrxEnum() { }
    47             OrxEnum(int type)                  { type_ = type; }
     64            OrxEnum(int type)            { type_ = type; }
    4865            OrxEnum(const T& instance)   { type_ = instance.type_; }
    4966
    50             operator int()                     { return type_; }
     67            operator int()               { return type_; }
    5168            T& operator =(int type)      { type_ = type; return *this; }
    5269            bool operator <(const T& right) const { return (type_ < right.type_); }
    … …  
    5976}
    6077
     78/// See orxonox::OrxEnum for more info
    6179#define OrxEnumConstructors(enumName)                        \
    6280enumName() { }                                               \

  • code/trunk/src/libraries/util/OutputHandler.cc

    r6417 r7401  
    6767        @brief
    6868            Gets temporary log path and starts the log file
    69         @param outputHandler
    70             This is only required to avoid another call to getInstance (this c'tor was
    71             called from getInstance!)
    7269        */
    7370        LogFileWriter()
    … …  
    117114
    118115    private:
    119         std::ofstream logFile_;     //! File handle for the log file
    120         std::string   logFilename_; //! Filename of the log file
     116        std::ofstream logFile_;     //!< File handle for the log file
     117        std::string   logFilename_; //!< Filename of the log file
    121118    };
    122119
    … …  
    162159        @brief
    163160            Sets the right soft debug level and registers itself
    164         @param outputHandler
    165             This is only required to avoid another call to getInstance (this c'tor was
    166             called from getInstance!)
    167161        */
    168162        MemoryLogWriter()
    … …  
    186180
    187181    private:
    188         std::ostringstream                        buffer_; //! Stream object used to process the output
    189         std::vector<std::pair<int, std::string> > output_; //! Vector containing ALL output
     182        std::ostringstream                        buffer_; //!< Stream object used to process the output
     183        std::vector<std::pair<int, std::string> > output_; //!< Vector containing ALL output
    190184    };
    191185

  • code/trunk/src/libraries/util/OutputHandler.h

    r7284 r7401  
    2929/**
    3030@file
     31@ingroup Util Output
    3132@brief
    32     Declaration of classes related to output (logging).
     33    Declaration of classes related to output (logging), most notably OutputHandler and OutputListener.
    3334*/
    3435
    … …  
    5051        Denotes different levels of text output (log output)
    5152
    52         0, None   : Very important output
    53         1, Error  : Errors
    54         2, Warning: Warnings
    55         3, Info   : Information
    56         4, Debug  : Debug information
    57         5, Verbose: More debug information
    58         6, Ultra  : Crazy debug information
     53         - 0, None   : Very important output
     54         - 1, Error  : Errors
     55         - 2, Warning: Warnings
     56         - 3, Info   : Information
     57         - 4, Debug  : Debug information
     58         - 5, Verbose: More debug information
     59         - 6, Ultra  : Crazy debug information
    5960    */
    6061    namespace OutputLevel
    … …  
    7980    /**
    8081    @brief
    81         The OutputHandler acts like std::cout, but output isn't only shown in the console.
    82 
    83         You can register your own listener for output by inheriting from OutputListner.
     82        The OutputHandler acts like @c std::cout, but output isn't only shown in the console.
     83
     84        Output passed to the OutputHandler is distributed to all registered listeners,
     85        for example the console, the logfile, or the ingame shell.
     86
     87        You can register your own listener for output by inheriting from OutputListener.
    8488        And if you need the output previously processed, iterate over it with
    85         OutputHandler::getOutputVector[Begin/End].
     89        OutputHandler::getOutputVectorBegin and OutputHandler::getOutputVectorEnd.
     90
    8691        The way to output text is to first set the desired output level with
    87         OutputHandler::getOutStream(level) and then use the "<<" operator like with std::cout.
     92        @ref getOutStream "OutputHandler::getOutStream(level)" and then use
     93        the "<<" operator like with @c std::cout. Alternatively you can use the COUT() macro.
    8894    */
    8995    class _UtilExport OutputHandler
    … …  
    213219            OutputHandler();
    214220            ~OutputHandler();
    215             OutputHandler(const OutputHandler& rhs); //! Unused and undefined
     221            OutputHandler(const OutputHandler& rhs);      //!< Copy-constructor: Unused and undefined
    216222
    217223            std::list<OutputListener*> listeners_;        //!< Array with all registered output listeners

  • code/trunk/src/libraries/util/Scope.cc

    r5738 r7401  
    2727 */
    2828
     29/**
     30    @file
     31    @brief Static linkage of the two maps in orxonox::ScopeManager.
     32*/
     33
    2934#include "Scope.h"
    3035

  • code/trunk/src/libraries/util/Scope.h

    r7266 r7401  
    2727 */
    2828
     29/**
     30@file
     31@ingroup SingletonScope
     32@brief Declaration of the classes that are needed to use Scopes:
     33orxonox::Scope, orxonox::ScopeListener, and orxonox::ScopeManager.
     34
     35@anchor Scope
     36
     37A virtual scope can be represented by an instance of class orxonox::Scope. orxonox::Scope<@a scope> is a template
     38an its template argument defines the name of the virtual scope. See orxonox::ScopeID for an enumeration of the
     39available values for @a scope. The orxonox::Scope object for a given @a scope can be activated or deactivated.
     40Instances of orxonox::ScopeListener can register for a given @a scope and will get a notification if the
     41corresponding orxonox::Scope object changes its state.
     42
     43To avoid multiple instances of orxonox::Scope<@a scope> in different libraries, each instance of orxonox::Scope
     44registers in orxonox::ScopeManager, where they are linked statically in the util library.
     45
     46Scopes are usually used to control the creation and destruction of Singletons.
     47
     48@see orxonox::ScopedSingletonManager
     49@see orxonox::Singleton
     50*/
     51
    2952#ifndef __Util_Scope_H__
    3053#define __Util_Scope_H__
    … …  
    4265{
    4366    /**
    44         @brief The ScopeManager stores the variables of the scope templates in a statically linked context.
     67        @brief The ScopeManager stores the variables of the Scope templates in a statically linked context.
     68
     69        If all Scope objects are managed by this class, they are statically linked in the util library.
     70        Without this, a new instance of Scope<T> for each T would be created in every library of Orxonox,
     71        which is of course not the desired behavior.
     72
     73        @see See @ref Scope "this description" for details about the interrelationship of Scope, ScopeListener, and ScopeManager.
    4574    */
    4675    class _UtilExport ScopeManager
    … …  
    5685
    5786    /**
    58         @brief ScopeListeners register themselves in the corresponding scope and wait for notifications.
     87        @brief ScopeListeners register themselves in the corresponding Scope and wait for notifications.
     88        Notifications are sent if a Scope is activated or deactivated.
     89
     90        @see See @ref Scope "this description" for details about the interrelationship of Scope, ScopeListener, and ScopeManager.
    5991    */
    6092    class _UtilExport ScopeListener
    … …  
    86118        Objects inheriting from a ScopeListener are registered in a list (different for each scope).
    87119        If the scope gets activated or deactivated, all objects in this list are notified.
     120
     121        @see See @ref Scope "this description" for details about the interrelationship of Scope, ScopeListener, and ScopeManager.
    88122    */
    89123    template <ScopeID::Value scope>
    … …  
    130164            }
    131165
     166            //! Deactivates the listeners of this scope in case the scope is destroyed or the construction fails.
    132167            void deactivateListeners()
    133168            {

  • code/trunk/src/libraries/util/ScopedSingletonManager.cc

    r7284 r7401  
    2727 */
    2828
     29/**
     30    @file
     31    @brief Static linkage of the ScopedSingletonManager maps.
     32*/
     33
    2934#include "ScopedSingletonManager.h"
    3035

  • code/trunk/src/libraries/util/ScopedSingletonManager.h

    r7284 r7401  
    2626 *
    2727 */
     28
     29/**
     30    @file
     31    @ingroup SingletonScope
     32    @brief Definition of orxonox::ScopedSingletonManager, orxonox::ClassScopedSingletonManager, and the ManageScopedSingleton macro.
     33
     34    ScopedSingletonManager is used to create and destroy Singletons that belong to
     35    a given Scope. For each one of these singletons, the macro ManageScopedSingleton()
     36    has to be called to register the singleton with orxonox::ScopedSingletonManager.
     37
     38    See @ref SingletonExample "this code" for an example.
     39
     40    @see orxonox::Singleton
     41    @see orxonox::Scope
     42*/
    2843
    2944#ifndef __ScopedSingletonManager_H__
    … …  
    3853#include "util/Singleton.h"
    3954
     55/**
     56    @brief Registers an orxonox::Singleton with orxonox::ScopedSingletonManager.
     57    @param className The name of the singleton class
     58    @param scope The scope in which the singleton should exist
     59    @param allowedToFail If true, the singleton is allowed to fail and thus a try-catch block is used when creating the singleton.
     60
     61    If this macro is called for a singleton, it is registered with ScopedSingletonManager
     62    and will thus be created if its scope becomes active and destroyed if is deactivated.
     63*/
    4064#define ManageScopedSingleton(className, scope, allowedToFail) \
    4165    className* className::singletonPtr_s = NULL; \
    … …  
    4670    class OrxonoxClass;
    4771
     72    /**
     73        @brief Base class of ClassScopedSingletonManager, implements some static functions
     74        used to dispatch calls to preUpdate and postUpdate to all instances of this class.
     75        It also keeps track of all existing ScopedSingletonManagers and stores them in a
     76        map, sorted by the scope they belong to.
     77    */
    4878    class _UtilExport ScopedSingletonManager
    4979    {
    5080        public:
     81            /// Constructor: Initializes all the values
    5182            ScopedSingletonManager(const std::string& className, ScopeID::Value scope)
    5283                : className_(className)
    … …  
    5485            { }
    5586            virtual ~ScopedSingletonManager() { }
     87
     88            /// Adds a new instance of ScopedSingletonManager to the map.
    5689            static void addManager(ScopedSingletonManager* manager);
    5790
     91            /// Calls preUpdate in all instances of ScopedSingletonManager that are registered in the map.
    5892            template<ScopeID::Value scope>
    5993            static void preUpdate(const Clock& time)
    … …  
    6498            }
    6599            virtual void preUpdate(const Clock& time) = 0;
     100
     101            /// Calls postUpdate in all instances of ScopedSingletonManager that are registered in the map.
    66102            template<ScopeID::Value scope>
    67103            static void postUpdate(const Clock& time)
    … …  
    78114
    79115        protected:
    80             const std::string className_;
    81             const ScopeID::Value scope_;
     116            const std::string className_;   ///< The name of the scoped singleton class that is managed by this object
     117            const ScopeID::Value scope_;    ///< The scope of the singleton that is managed by this object
    82118    };
    83119
     120    /**
     121        @anchor ClassScopedSingletonManager
     122
     123        @brief Manages a scoped singleton for a given scope.
     124        @param T The managed singleton class
     125        @param scope The scope in which the singleton @a T should be active
     126        @param allowedToFail If true, a specialization of this template is used, that uses try-catch blocks to handle possible failures.
     127
     128        This class inherits from ScopeListener for the given scope and thus its functions
     129        activated() and deactivated() are called whenever the Scope changes its state.
     130
     131        If the Scope is activated, a new instance of @a T (which must be a singleton) is created.
     132        If the Scope is deactivated, the singleton is destroyed.
     133
     134        @see Singleton
     135    */
    84136    template <class T, ScopeID::Value scope, bool allowedToFail>
    85137    class ClassScopedSingletonManager : public ScopedSingletonManager, public ScopeListener
    86138    {
    87139    public:
     140        //! Constructor: Initializes the singleton pointer and passes the scope to ScopedSingletonManager and ScopeListener
    88141        ClassScopedSingletonManager(const std::string& className)
    89142            : ScopedSingletonManager(className, scope)
    … …  
    113166        }
    114167
     168        //! Destroys the singleton instance - overloaded for OrxonoxClass, calls OrxonoxClass::destroy()
    115169        void destroy(OrxonoxClass*)
    116170        {
    117171            singletonPtr_->destroy();
    118172        }
     173        //! Destroys the singleton instance - overloaded for all other pointers, calls delete
    119174        void destroy(void*)
    120175        {
    … …  
    139194
    140195    private:
    141         T* singletonPtr_;
     196        T* singletonPtr_;   ///< Unique instance of the singleton class @a T
    142197    };
    143198
     199    /**
     200        @brief This class partially spezializes ClassScopedSingletonManager for classes @a T that are allowed to fail.
     201        @param T The managed singleton class
     202        @param scope The scope in which the singleton @a T should be active
     203
     204        Because @a T could fail when being created, this partial spezialization of ClassScopedSingletonManager
     205        uses a try-catch block to handle exceptions.
     206
     207        See @ref ClassScopedSingletonManager for a full documentation of the basis template.
     208    */
    144209    template <class T, ScopeID::Value scope>
    145210    class ClassScopedSingletonManager<T, scope, true> : public ScopedSingletonManager, public ScopeListener
    146211    {
    147212    public:
     213        //! Constructor: Initializes the singleton pointer and passes the scope to ScopedSingletonManager and ScopeListener
    148214        ClassScopedSingletonManager(const std::string& className)
    149215            : ScopedSingletonManager(className, scope)
    … …  
    180246        }
    181247
     248        //! Destroys the singleton instance - overloaded for OrxonoxClass, calls OrxonoxClass::destroy()
    182249        void destroy(OrxonoxClass* ptr)
    183250        {
    184251            singletonPtr_->destroy();
    185252        }
     253        //! Destroys the singleton instance - overloaded for void*, calls delete
    186254        void destroy(void* ptr)
    187255        {
    … …  
    208276
    209277    private:
    210         T* singletonPtr_;
     278        T* singletonPtr_;   ///< Unique instance of the singleton class @a T
    211279    };
    212280}

  • code/trunk/src/libraries/util/Serialise.h

    r7182 r7401  
    2929/**
    3030    @file
     31    @ingroup Util
    3132    @brief Functions to serialise most of the types/classed used in Orxonox
    3233*/
    … …  
    5354    template <class T> inline bool checkEquality( const T& variable, uint8_t* mem );
    5455
    55  
     56
    5657  // =========== char*
    57    
     58
    5859  inline uint32_t returnSize( char*& variable )
    5960  {
    6061    return strlen(variable)+1;
    6162  }
    62      
     63
    6364  inline void saveAndIncrease( char*& variable, uint8_t*& mem )
    6465  {
    … …  
    6667    mem += returnSize(variable);
    6768  }
    68        
     69
    6970  inline void loadAndIncrease( char*& variable, uint8_t*& mem )
    7071  {
    … …  
    7677    mem += len;
    7778  }
    78          
     79
    7980  inline bool checkEquality( char*& variable, uint8_t* mem )
    8081  {
    8182    return strcmp(variable, (char*)mem)==0;
    8283  }
    83    
     84
    8485// =================== Template specialisation stuff =============
    8586
    … …  
    423424        return memcmp(&temp, mem, sizeof(uint64_t))==0;
    424425    }
    425        
     426
    426427// =========== string
    427428

  • code/trunk/src/libraries/util/SharedPtr.cc

    r7284 r7401  
    2727 */
    2828
     29/**
     30    @file
     31    @brief Static linkage of the SmallObjectAllocator used by SharedPtr.
     32*/
     33
    2934#include "SharedPtr.h"
    3035
    3136namespace orxonox
    3237{
    33     SmallObjectAllocator& createSharedCounterPool()
     38    namespace detail
    3439    {
    35         static SmallObjectAllocator instance(sizeof(SharedCounterImpl<void>));
    36         return instance;
     40        SmallObjectAllocator& createSharedCounterPool()
     41        {
     42            static SmallObjectAllocator instance(sizeof(SharedCounterImpl<void>));
     43            return instance;
     44        }
    3745    }
    3846}

  • code/trunk/src/libraries/util/SharedPtr.h

    r7284 r7401  
    2727 */
    2828
     29/**
     30    @defgroup SharedPtr SharedPtr<T>
     31    @ingroup Util
     32*/
     33
     34/**
     35    @file
     36    @ingroup SharedPtr
     37    @brief Definition of the SharedPtr template that is used to manage pointers.
     38
     39    @anchor SharedPtrExample
     40
     41    The orxonox::SharedPtr template can be used to manage a pointer to an object
     42    that was created with new. The SharedPtr acts like the pointer itself, but it
     43    keeps track of the number of references to it. If all references are removed,
     44    SharedPtr deletes the managed object automatically.
     45
     46    Example:
     47
     48    Classic implementation using new and delete:
     49    @code
     50    void someFunction()
     51    {
     52        MyClass* object = new MyClass();            // Create a new instance of MyClass
     53
     54        object->myFunction();                       // Calls MyClass::myFunction()
     55
     56        delete object;                              // Delete the object at the end of the scope
     57    }
     58    @endcode
     59
     60    The same function using SharedPtr:
     61    @code
     62    void someFunction()
     63    {
     64        SharedPtr<MyClass> object = new MyClass();  // Create a new instance of MyClass and store its pointer in a SharedPtr
     65
     66        object->myFunction();                       // Calls MyClass::myFunction()
     67
     68    }                                               // At the end of the scope, the SharedPtr is destroyed. Because no other SharedPtrs
     69                                                    // point at the object, the object itself is also destroyed automatically
     70    @endcode
     71
     72    This is especially handy if you do not know what will happen with an object that was
     73    created with new, for example if you pass it to another object. If multiple instances
     74    share a pointer to the same object, none of these instances can delete the object
     75    without interfering with the other instances. But if none of the instances destroy the
     76    object, it will never be destroyed and results in a memory leak. With a SharedPtr
     77    however you don't have to think about destroying the object, because the SharedPtr
     78    itself keeps track of the references.
     79
     80    Example:
     81
     82    Classic implementation using new and delete:
     83    @code
     84    class OtherClass                                    // Declaration of some class
     85    {
     86        public:
     87            OtherClass(MyClass* object)                 // Constructor
     88            {
     89                this->object_ = object;                 // Assigns the pointer to the member variable object_
     90            }
     91
     92            ~OtherClass()                               // Destructor
     93            {
     94                ???                                     // What to do with object_?
     95            }
     96
     97        private:
     98            MyClass* object_;                           // A pointer to the object
     99    };
     100
     101    void someFunction()
     102    {
     103        MyClass* object = new MyClass();                // Create a new instance of MyClass
     104
     105        OtherClass* other1 = new OtherClass(object);    // Create an instance of OtherClass and pass the object pointer
     106        OtherClass* other2 = new OtherClass(object);    // "
     107        OtherClass* other3 = new OtherClass(object);    // "
     108
     109        ???                                             // What happens with object now?
     110    }
     111    @endcode
     112
     113    If you use SharedPtr<MyClass> instead of a classic MyClass* pointer, the instance of
     114    MyClass would be automatically destroyed if all instances of OtherClass are destroyed.
     115    You don't need any code in the destructor and you can completely forget about the
     116    object, because its managed by the SharedPtr.
     117
     118    The same code using SharedPtr:
     119    @code
     120    class OtherClass                                        // Declaration of some class
     121    {
     122        public:
     123            OtherClass(const SharedPtr<MyClass>& object)    // Constructor
     124            {
     125                this->object_ = object;                     // Assigns the pointer to the member variable object_
     126            }
     127
     128        private:
     129            SharedPtr<MyClass> object_;                     // A SharedPtr to the object
     130    };
     131
     132    void someFunction()
     133    {
     134        SharedPtr<MyClass> object = new MyClass();          // Create a new instance of MyClass
     135
     136        OtherClass* other1 = new OtherClass(object);        // Create an instance of OtherClass and pass the object pointer
     137        OtherClass* other2 = new OtherClass(object);        // "
     138        OtherClass* other3 = new OtherClass(object);        // "
     139
     140    }                                                       // The SmartPtr "object" is destroyed at the end of the scope,
     141                                                            // but the three instances of OtherClass keep the object alive
     142                                                            // until they are all destroyed.
     143    @endcode
     144*/
     145
    29146#ifndef _SharedPtr_H__
    30147#define _SharedPtr_H__
    … …  
    39156namespace orxonox
    40157{
    41     class SharedCounter
    42     {
    43         public:
    44             SharedCounter() : count_(1) {}
    45             virtual void destroy() = 0;
    46 
    47             int count_;
    48     };
    49 
    50     template <class T>
    51     class SharedCounterImpl : public SharedCounter
    52     {
    53         public:
    54             SharedCounterImpl(T* pointer) : pointer_(pointer) {}
    55 
    56             void destroy()
    57             {
    58                 delete this->pointer_;
    59             }
    60 
    61         private:
    62             T* pointer_;
    63     };
    64 
    65     _UtilExport SmallObjectAllocator& createSharedCounterPool();
    66 
    67     FORCEINLINE SmallObjectAllocator& getSharedCounterPool()
    68     {
    69         static SmallObjectAllocator& instance = createSharedCounterPool();
    70         return instance;
     158    namespace detail
     159    {
     160        /// BaseClass of SharedCounterImpl, has a counter that is initialized with 1
     161        class SharedCounter
     162        {
     163            public:
     164                SharedCounter() : count_(1) {}
     165                virtual void destroy() = 0;
     166
     167                int count_;
     168        };
     169
     170        /// Child class of SharedCounter, keeps a pointer to an object of type T that can be destroyed with destroy()
     171        template <class T>
     172        class SharedCounterImpl : public SharedCounter
     173        {
     174            public:
     175                SharedCounterImpl(T* pointer) : pointer_(pointer) {}
     176
     177                void destroy()
     178                {
     179                    delete this->pointer_;
     180                }
     181
     182            private:
     183                T* pointer_;
     184        };
     185
     186        _UtilExport SmallObjectAllocator& createSharedCounterPool();
     187
     188        FORCEINLINE SmallObjectAllocator& getSharedCounterPool()
     189        {
     190            static SmallObjectAllocator& instance = createSharedCounterPool();
     191            return instance;
     192        }
    71193    }
    72194
     195    /**
     196        @brief The SharedPtr template is a utility to manage pointers to an object.
     197        @param T The type of the managed object
     198
     199        SharedPtr acts like a real pointer, except that it keeps track of the number of
     200        references to the object. If the the number of references drops to zero, the
     201        object is destroyed automatically.
     202
     203        @see See @ref SharedPtrExample "this description" for some examples and more information.
     204
     205        @note The number of references is stored in a separate object that is shared
     206        among all instances of SharedPtr that point to the same pointer. This object is
     207        also responsible for destroying the pointer if the reference counter becomes zero.
     208    */
    73209    template <class T>
    74210    class SharedPtr
    … …  
    78214
    79215        public:
     216            /// Default constructor, the pointer is set to NULL.
    80217            inline SharedPtr() : pointer_(0), counter_(0)
    81218            {
    82219            }
    83220
     221            /// Constructor, creates a SharedPtr that points to @a pointer, increments the counter.
    84222            inline SharedPtr(T* pointer) : pointer_(pointer), counter_(0)
    85223            {
    86224                if (this->pointer_)
    87225                {
    88                     void* chunk = getSharedCounterPool().alloc();
    89                     this->counter_ = new (chunk) SharedCounterImpl<T>(this->pointer_);
     226                    void* chunk = detail::getSharedCounterPool().alloc();
     227                    this->counter_ = new (chunk) detail::SharedCounterImpl<T>(this->pointer_);
    90228                }
    91229            }
    92230
     231            /// Copy-constructor, this SharedPtr now points to the same object like the other SharedPtr, increments the counter.
    93232            inline SharedPtr(const SharedPtr& other) : pointer_(other.pointer_), counter_(other.counter_)
    94233            {
    … …  
    97236            }
    98237
     238            /// Copy-constructor for SharedPtr with another template agument, increments the counter.
    99239            template <class O>
    100240            inline SharedPtr(const SharedPtr<O>& other) : pointer_(other.pointer_), counter_(other.counter_)
    … …  
    104244            }
    105245
     246            /// Destructor, decrements the counter and deletes the object if the counter becomes zero.
    106247            inline ~SharedPtr()
    107248            {
    … …  
    113254                    {
    114255                        this->counter_->destroy();
    115                         getSharedCounterPool().free(this->counter_);
     256                        detail::getSharedCounterPool().free(this->counter_);
    116257                    }
    117258                }
    118259            }
    119260
     261            /// Assigns a new object, decrements the counter of the old object, increments the counter of the new object.
    120262            inline SharedPtr& operator=(const SharedPtr& other)
    121263            {
    … …  
    124266            }
    125267
     268            /// Assigns a new object with another template argument, decrements the counter of the old object, increments the counter of the new object.
    126269            template <class O>
    127270            inline SharedPtr& operator=(const SharedPtr<O>& other)
    … …  
    131274            }
    132275
     276            /// Casts the pointer to another type
    133277            template <class O>
    134278            inline SharedPtr<O> cast() const
    … …  
    138282            }
    139283
     284            /// Overloaded -> operator, returns the pointer to the managed object.
    140285            inline T* operator->() const
    141286            {
    … …  
    144289            }
    145290
     291            /// Overloaded * operator, returns a reference ot the managed object.
    146292            inline T& operator*() const
    147293            {
    … …  
    150296            }
    151297
     298            /// Returns the pointer to the managed object.
    152299            inline T* get() const
    153300            {
    … …  
    155302            }
    156303
     304            /// Returns true if the pointer is not NULL.
    157305            inline operator bool() const
    158306            {
    … …  
    160308            }
    161309
     310            /// Swaps the pointer and the counter of two instances of SharedPtr with the same template argument.
    162311            inline void swap(SharedPtr& other)
    163312            {
    … …  
    167316
    168317        private:
    169             inline SharedPtr(T* pointer, SharedCounter* counter) : pointer_(pointer), counter_(counter)
     318            /// Private constructor, used by the cast() function.
     319            inline SharedPtr(T* pointer, detail::SharedCounter* counter) : pointer_(pointer), counter_(counter)
    170320            {
    171321                if (this->pointer_)
    … …  
    173323            }
    174324
    175             T* pointer_;
    176             SharedCounter* counter_;
     325            T* pointer_;                        ///< A pointer to the managed object of type @a T
     326            detail::SharedCounter* counter_;    ///< A pointer to the shared reference counter
    177327    };
    178328
     329    /**
     330        @brief A child class of SharedPtr, used to reflect the hierarchy of the underlying class @a T.
     331        @param T The type of the managed object
     332        @param Parent The type of the SharedPtr that manages the parent class of @a T
     333
     334        This class is used to reflect the hierarchy of the underlying class @a T.
     335        For example the @c Functor classes: While a @c Functor* pointer would be managed by
     336        @c SharedPtr<Functor>, the child class @c FunctorStatic is managed by the class
     337        <tt>SharedChildPtr<FunctorStatic, SharedPtr<Functor> ></tt>.
     338
     339        The second template argument @a Parent is used as the parent class of
     340        SharedChildPtr. This means that each instance of <tt>SharedChildPtr<T, Parent></tt>
     341        can be upcasted to @c Parent.
     342
     343        So for example this works:
     344        @code
     345        SharedChildPtr<FunctorStatic, SharedPtr<Functor> > functorStatic = createFunctor(&MyClass::myStaticFunction);
     346        SharedPtr<Functor> functor = functorStatic;
     347        @endcode
     348
     349        @note There are some typedefs and more to make the usage of SharedChildPtr easier
     350        for the classes Functor and Executor. See FunctorPtr.h and ExecutorPtr.h. The above
     351        example could thus be simplified the following way:
     352        @code
     353        FunctorStaticPtr functorStatic = createFunctor(&MyClass::myStaticFunction);
     354        FunctorPtr functor = functorStatic;
     355        @endcode
     356
     357        @see See SharedPtr for more information about the base class SharedPtr.
     358        @see See @ref SharedPtrExample "this description" for some examples about how to use SharedPtr.
     359    */
    179360    template <class T, class Parent>
    180361    class SharedChildPtr : public Parent

  • code/trunk/src/libraries/util/SignalHandler.h

    r5738 r7401  
    2929/**
    3030    @file
     31    @ingroup Util
    3132    @brief Declaration of the SignalHandler class.
    3233*/
    … …  
    6869    typedef std::list<SignalCallbackRec> SignalCallbackList;
    6970
     71    /// The SignalHandler is used to catch signals like SIGSEGV and write a backtrace to the logfile.
    7072    class SignalHandler : public Singleton<SignalHandler>
    7173    {
    … …  
    99101namespace orxonox
    100102{
     103    /// The SignalHandler is used to catch signals like SIGSEGV and write a backtrace to the logfile. Not implemented on Windows.
    101104    class _UtilExport SignalHandler : public Singleton<SignalHandler>
    102105    {

  • code/trunk/src/libraries/util/Singleton.h

    r7163 r7401  
    2727 */
    2828
     29/**
     30    @defgroup SingletonScope Singletons and Scope
     31    @ingroup Util
     32*/
     33
     34/**
     35    @file
     36    @ingroup SingletonScope
     37    @brief Definition of the Singleton template that is used as base class for classes that allow only one instance.
     38
     39    @anchor SingletonExample
     40
     41    Classes that inherit from orxonox::Singleton follow the singleton pattern and thus
     42    allow only one instance of the class to exist. This istance is stored in a static
     43    variable called @c singletonPtr_s. orxonox::Singleton will access this variable, but
     44    it must be implemented in the deriving class.
     45
     46    Example:
     47    @code
     48    class TestSingleton : public Singleton<TestSingleton>   // inherit from Singleton, pass the own class as template argument
     49    {
     50        friend class Singleton<TestSingleton>;              // friend declaration so Singleton can access singletonPtr_s
     51
     52        public:
     53            TestSingleton();                                // public constructor because we may want to manage this singleton
     54                                                            //     with an orxonox::ScopedSingletonManager (see below)
     55            virtual ~TestSingleton();                       // public destructor
     56
     57            void testFunction();                            // put your functions here
     58
     59        private:
     60            int testValue_;                                 // put your variables here
     61
     62            static TestSingleton* singletonPtr_s;           // static singleton instance pointer, used by the Singleton template
     63    };
     64    @endcode
     65
     66    And don't forget to initialize the static singleton pointer in the source (*.cc) %file:
     67    @code
     68    TestSingleton* TestSingleton::singletonPtr_s = NULL;
     69    @endcode
     70
     71    Usually a singleton gets created automatically when it is first used, but it will never
     72    be destroyed (unless the singleton explicitly deletes itself). To allow controlled
     73    construction and destruction, the singleton can be put within a virtual scope. This is
     74    done by registering the singleton class with orxonox::ScopedSingletonManager. To
     75    do so, the ManageScopedSingleton() macro has to be called:
     76
     77    @code
     78    ManageScopedSingleton(TestSingleton, ScopeID::Graphics, false); // muste be called in a source (*.cc) file
     79    @endcode
     80
     81    @b Important: If you call ManageScopedSingleton(), you don't have to initialize singletonPtr_s anymore,
     82    because that's already done by the macro.
     83
     84    Now the singleton TestSingleton gets automatically created if the scope Graphics becomes
     85    active and also gets destroyed if the scope is deactivated.
     86
     87    Note that not all singletons must register with a scope, but it's recommended.
     88
     89    If a class inherits from orxonox::Singleton, it also inherits its functions. The most important
     90    function is orxonox::Singleton::getInstance() which returns a reference to the only instance
     91    of the singleton.
     92
     93    Example:
     94    @code
     95    TestSingleton::TestSingleton()                          // implement the constructor
     96    {
     97        this->testValue_ = 15;
     98    }
     99
     100    void TestSingleton::testFunction()                      // implement testFunction
     101    {
     102        COUT(0) << "My value is " << this->testValue_ << std::endl;
     103    }
     104
     105    TestSingleton::getInstance().testFunction();            // prints "My value is 15"
     106    @endcode
     107*/
     108
    29109#ifndef __Util_Singleton_H__
    30110#define __Util_Singleton_H__
    … …  
    42122
    43123        Usage:
    44         Inherit publicly from Singleton<MyClass> and provide access to
    45         MyClass::singletonPtr_s.
     124        Inherit publicly from Singleton<MyClass> and provide access to MyClass::singletonPtr_s.
    46125        This can easily be done with a friend declaration.
     126
     127        See @ref SingletonExample "this example" for an exemplary implementation.
    47128    */
    48129    template <class T>
    … …  
    80161        }
    81162
    82         //! Constructor resets the singleton instance pointer
     163        //! Destructor resets the singleton instance pointer
    83164        ~Singleton()
    84165        {

  • code/trunk/src/libraries/util/SmallObjectAllocator.cc

    r7284 r7401  
    2727 */
    2828
     29/**
     30    @file
     31    @brief Implementation of SmallObjectAllocator
     32*/
     33
    2934#include "SmallObjectAllocator.h"
    3035
    3136namespace orxonox
    3237{
     38    /**
     39        @brief Constructor: initializes the allocator and its values.
     40        @param objectSize The size in bytes (returned by sizeof()) of the allocated objects
     41        @param numObjects The number of objects that are allocated in one block of memory
     42    */
    3343    SmallObjectAllocator::SmallObjectAllocator(size_t objectSize, size_t numObjects)
    3444    {
    35         this->objectSize_ = std::max(objectSize, sizeof(Chunk));
    36         this->numObjects_ = numObjects;
     45        this->chunkSize_ = std::max(objectSize, sizeof(Chunk)); // the chunk's size will be the maximum of the object's size and the size of a Chunk object itself
     46        this->numChunksPerBlock_ = numObjects;
    3747        this->first_ = 0;
    3848    }
    3949
     50    /**
     51        @brief Destructor: deletes the allocated memory blocks.
     52    */
    4053    SmallObjectAllocator::~SmallObjectAllocator()
    4154    {
    … …  
    4457    }
    4558
     59    /**
     60        @brief Helper function, used to set the next_ pointer of a Chunk.
     61    */
    4662    /* static */ void SmallObjectAllocator::setNext(void* chunk, void* next)
    4763    {
    … …  
    4965    }
    5066
     67    /**
     68        @brief Helper function, returns the next_ pointer of a Chunk
     69    */
    5170    /* static */ void* SmallObjectAllocator::getNext(void* chunk)
    5271    {
    … …  
    5473    }
    5574
     75    /**
     76        @brief Returns the first free memory chunk or allocates a new block of memory.
     77    */
    5678    void* SmallObjectAllocator::alloc()
    5779    {
     80        // get the first free chunk
    5881        void* chunk = this->first_;
    5982
     83        // check if the chunk exists
    6084        if (chunk)
    6185        {
     86            // yes it does - the first_ pointer now points to the second element in the list
    6287            this->first_ = getNext(chunk);
    6388        }
    6489        else
    6590        {
    66             char* block = new char[this->objectSize_ * this->numObjects_];
     91            // no it doesnt - allocate a new block of memory
     92            char* block = new char[this->chunkSize_ * this->numChunksPerBlock_];
    6793            this->blocks_.push_back(block);
    6894
    69             for (size_t i = 1; i < this->numObjects_ - 1; ++i)
    70                 setNext(block + i * this->objectSize_, block + (i + 1) * this->objectSize_);
     95            // iterate through the chunks in the new memory block and link them together to a single linked list
     96            for (size_t i = 1; i < this->numChunksPerBlock_ - 1; ++i)
     97                setNext(block + i * this->chunkSize_, block + (i + 1) * this->chunkSize_);
    7198
    72             setNext(block + (this->numObjects_ - 1) * this->objectSize_, 0);
     99            // the next_ pointer of the last chunk must point to NULL
     100            setNext(block + (this->numChunksPerBlock_ - 1) * this->chunkSize_, 0);
    73101
    74             this->first_ = block + this->objectSize_;
     102            // The second chunk in the block is assigned to the first_ pointer
     103            this->first_ = block + this->chunkSize_;
    75104
     105            // The first chunk in the block is returned
    76106            chunk = block;
    77107        }
    78108
     109        // return the pointer to the chunk
    79110        return chunk;
    80111    }
    81112
     113    /**
     114        @brief Puts the memory chunk back on the list of free memory.
     115    */
    82116    void SmallObjectAllocator::free(void* chunk)
    83117    {
     118        // The first_ pointer points to the freed chunk, its next_ pointer points to the rest of the list
    84119        setNext(chunk, this->first_);
    85120        this->first_ = chunk;

  • code/trunk/src/libraries/util/SmallObjectAllocator.h

    r7284 r7401  
    2727 */
    2828
     29/**
     30    @defgroup SmallObjectAllocator SmallObjectAllocator
     31    @ingroup Util
     32*/
     33
     34/**
     35    @file
     36    @ingroup SmallObjectAllocator
     37    @brief Declaration of SmallObjectAllocator
     38
     39    @anchor SmallObjectAllocatorExample
     40
     41    The default implementations of new and delete are designed to work with objects of
     42    arbitrary size. They are thus not optimal for small objects.
     43    @ref orxonox::SmallObjectAllocator "SmallObjectAllocator" allocates a large memory
     44    block and divides it into small chunks. These chunks are returned by the function
     45    @ref orxonox::SmallObjectAllocator::alloc() "alloc()" and can be used to create a
     46    new object using the placement new operator. Instead of delete, the function
     47    @ref orxonox::SmallObjectAllocator::free() "free()" is used to give the memory
     48    back to SmallObjectAllocator.
     49
     50    Example:
     51    @code
     52    SmallObjectAllocator allocator(sizeof(MySmallObject));  // Create an allocator. The size of the memory chunks must equal the size of the desired class
     53
     54    void* chunk = allocator.alloc();                        // Allocate a memory chunk
     55    MySmallObject* object = new (chunk) MySmallObject();    // Call the placement new operator
     56
     57    object->someFunction();                                 // Do something with the object
     58
     59    object->~MySmallObject();                               // Call the destructor
     60    allocator.free(object);                                 // Free the allocated memory
     61    @endcode
     62
     63    @b Important: You have to call the destructor of the object manually, because this
     64    is not automatically done by the allocator nor free().
     65
     66    @note The destructor can be ignored if it is empty or not implemented. This saves
     67    another amount of time.
     68
     69    @remarks For a distributed usage of SmallObjectAllocator it may be a good idea to
     70    create a static function that returns an instance to it. The allocator then works
     71    like a singleton and can be accesses from everywhere.
     72*/
     73
    2974#ifndef _SmallObjectAllocator_H__
    3075#define _SmallObjectAllocator_H__
    … …  
    3580namespace orxonox
    3681{
     82    /**
     83        @brief This class is used to allocate and free small objects (usually not polymorphic).
     84
     85        SmallObjectAllocator provides a fast alternative to new and delete for small objects.
     86
     87        @see See @ref SmallObjectAllocatorExample "this description" for more information and an example.
     88    */
    3789    class _UtilExport SmallObjectAllocator
    3890    {
     91        /// The memory chunk is at the same time an element of a single linked list.
    3992        struct Chunk
    4093        {
    41             Chunk* next_;
     94            Chunk* next_;   ///< A pointer to the next chunk in the list
    4295        };
    4396
    … …  
    53106            static void* getNext(void* chunk);
    54107
    55             void* first_;
    56             size_t objectSize_;
    57             size_t numObjects_;
     108            void* first_;                   ///< A pointer to the first free memory chunk
     109            size_t chunkSize_;              ///< The size of each chunk (and usually also the size of the created objects)
     110            size_t numChunksPerBlock_;      ///< The number of chunks per memory block
    58111
    59             std::vector<char*> blocks_;
     112            std::vector<char*> blocks_;     ///< A list of all allocated memory blocks (used to destroy them again)
    60113    };
    61114}

  • code/trunk/src/libraries/util/StringUtils.cc

    r7284 r7401  
    4141namespace orxonox
    4242{
     43    /// A blank string (""). Used to return a blank string by reference.
    4344    std::string BLANKSTRING;
    4445
     46    /// Returns a string of a unique number. This function is guaranteed to never return the same string twice.
    4547    std::string getUniqueNumberString()
    4648    {
    … …  
    4850    }
    4951
    50     /**
    51         @brief Removes all whitespaces from a string.
    52         @param str The string to strip
    53     */
     52    /// Removes all whitespaces from a string.
    5453    void strip(std::string* str)
    5554    {
    … …  
    6362    }
    6463
    65     /**
    66         @brief Returns a copy of a string without whitespaces.
    67         @param str The string to strip
    68         @return The stripped line
    69     */
     64    /// Returns a copy of a string without whitespaces.
    7065    std::string getStripped(const std::string& str)
    7166    {
    … …  
    7570    }
    7671
    77     /**
    78         @brief Returns a copy of a string without trailing whitespaces.
    79         @param str The string
    80         @return The modified copy
    81     */
     72    /// Returns a copy of a string without trailing whitespaces.
    8273    std::string removeTrailingWhitespaces(const std::string& str)
    8374    {
    … …  
    9081
    9182    /**
    92         @brief Returns the position of the next quote in the string, starting with start.
     83        @brief Returns the position of the next quotation mark in the string, starting with start.
    9384        @param str The string
    94         @param start The startposition
    95         @return The position of the next quote (std::string::npos if there is no next quote)
     85        @param start The first position to look at
     86        @return The position of the next quotation mark (@c std::string::npos if there is none)
    9687    */
    9788    size_t getNextQuote(const std::string& str, size_t start)
    … …  
    115106
    116107    /**
    117         @brief Returns true if pos is between two quotes.
     108        @brief Returns true if pos is between two quotation marks.
    118109        @param str The string
    119110        @param pos The position to check
    120         @return True if pos is between two quotes
     111        @return True if pos is between two quotation marks
    121112    */
    122113    bool isBetweenQuotes(const std::string& str, size_t pos)
    … …  
    140131    }
    141132
    142     /**
    143         @brief Returns true if the string contains something like '..."between quotes"...'.
    144         @param The string
    145         @return True if there is something between quotes
    146     */
     133    /// Returns true if the string contains something like '..."between quotaton marks"...'.
    147134    bool hasStringBetweenQuotes(const std::string& str)
    148135    {
    … …  
    152139    }
    153140
    154     /**
    155         @brief If the string contains something like '..."between quotes"...' then 'between quotes' gets returned (without quotes).
    156         @param The string
    157         @param The string between the quotes
    158     */
     141    /// If the string contains something like '..."between quotaton marks"...' then 'between quotaton marks' gets returned, otherwise "".
    159142    std::string getStringBetweenQuotes(const std::string& str)
    160143    {
    … …  
    168151
    169152    /**
    170         @brief Removes enclosing quotes if available (including whitespaces at the outside of the quotes).
    171         @brief str The string to strip
    172         @return The string with removed quotes
     153        @brief Removes enclosing quotation marks if available (including whitespaces at the outside of the quotation marks).
     154        @return The striped string without quotation marks
    173155    */
    174156    std::string stripEnclosingQuotes(const std::string& str)
    … …  
    208190
    209191    /**
    210         @brief Removes enclosing {braces} (braces must be exactly on the beginning and the end of the string).
    211         @param str The string to strip
    212         @return The striped string
     192        @brief Removes enclosing braces '{' and '}' (the braces must be exactly on the beginning and the end of the string).
     193        @return The striped string without braces
    213194    */
    214195    std::string stripEnclosingBraces(const std::string& str)
    … …  
    224205    /**
    225206        @brief Determines if a string is a comment (starts with a comment-symbol).
    226         @param str The string to check
    227         @return True = it's a comment
    228207
    229208        A comment is defined by a leading '#', '%', ';' or '//'.
    … …  
    253232    }
    254233
    255     /**
    256         @brief Determines if a string is empty (contains only whitespaces).
    257         @param str The string to check
    258         @return True = it's empty
    259     */
     234    /// Determines if a string is empty (contains only whitespaces).
    260235    bool isEmpty(const std::string& str)
    261236    {
    … …  
    263238    }
    264239
    265     /**
    266         @brief Determines if a string contains only numbers and maximal one '.'.
    267         @param str The string to check
    268         @return True = it's a number
    269     */
     240    /// Determines if a string contains only numbers and maximal one '.'.
    270241    bool isNumeric(const std::string& str)
    271242    {
    … …  
    288259    /**
    289260        @brief Adds backslashes to the given string which makes special chars visible. Existing slashes will be doubled.
    290         @param str The string to manipulate
    291         @return The string with added slashes
     261
     262        This function converts all special chars like line breaks, tabs, quotation marks etc. into
     263        a human readable format by adding a backslash. So for example "\n" will be converted to
     264        "\\" + "n".
     265
     266        This is usually used when a string is written to a file.
     267
     268        @see removeSlashes
    292269    */
    293270    std::string addSlashes(const std::string& str)
    … …  
    320297    /**
    321298        @brief Removes backslashes from the given string. Double backslashes are interpreted as one backslash.
    322         @param str The string to manipulate
    323         @return The string with removed slashes
     299
     300        This function removes all backslashes and converts the human readable equivalents of
     301        special chars like "\\" + "n" into their real meaning (in this case a line break or "\n").
     302
     303        This is usually used when reading a string from a file.
     304
     305        @see addSlashes
    324306    */
    325307    std::string removeSlashes(const std::string& str)
    … …  
    361343    }
    362344
    363     /**
    364         @brief Replaces each char between A and Z with its lowercase equivalent.
    365         @param str The string to convert
    366     */
     345    /// Replaces each char between A and Z with its lowercase equivalent.
    367346    void lowercase(std::string* str)
    368347    {
    … …  
    373352    }
    374353
    375     /**
    376         @brief Returns a copy of the given string without uppercase chars.
    377         @param str The string
    378         @return The copy
    379     */
     354    /// Returns a copy of the given string where all chars are converted to lowercase.
    380355    std::string getLowercase(const std::string& str)
    381356    {
    … …  
    385360    }
    386361
    387     /**
    388         @brief Replaces each char between a and z with its uppercase equivalent.
    389         @param str The string to convert
    390     */
     362    /// Replaces each char between a and z with its uppercase equivalent.
    391363    void uppercase(std::string* str)
    392364    {
    … …  
    397369    }
    398370
    399     /**
    400         @brief Returns a copy of the given string without lowercase chars.
    401         @param str The string
    402         @return The copy
    403     */
     371    /// Returns a copy of the given string where all chars are converted to uppercase.
    404372    std::string getUppercase(const std::string& str)
    405373    {
    … …  
    411379    /**
    412380        @brief Compares two strings ignoring different casing.
    413         @param s1 First string
    414         @param s2 Second string
     381        @return s1 == s1 -> returns 0 / s1 < s2 -> returns -1 / s1 >= s2 -> returns 1
    415382    */
    416383    int nocaseCmp(const std::string& s1, const std::string& s2)
    … …  
    438405
    439406    /**
    440         @brief Compares the first 'len' chars of two strings ignoring different casing.
     407        @brief Compares the first @a len chars of two strings ignoring different casing.
    441408        @param s1 First string
    442409        @param s2 Second string
    … …  
    463430    }
    464431
    465     /**
    466         @brief Returns true if the string contains a comment, introduced by #, %, ; or //.
     432    /// Returns true if the string contains a comment, introduced by #, %, ; or //.
     433    bool hasComment(const std::string& str)
     434    {
     435        return (getCommentPosition(str) != std::string::npos);
     436    }
     437
     438    /// If the string contains a comment, the comment gets returned (including the comment symbol), an empty string otherwise.
     439    std::string getComment(const std::string& str)
     440    {
     441        return str.substr(getCommentPosition(str));
     442    }
     443
     444    /// If the string contains a comment, the position of the comment-symbol gets returned, @c std::string::npos otherwise.
     445    size_t getCommentPosition(const std::string& str)
     446    {
     447        return getNextCommentPosition(str, 0);
     448    }
     449
     450    /**
     451        @brief Returns the position of the next comment-symbol, starting with @a start.
    467452        @param str The string
    468         @return True if the string contains a comment
    469     */
    470     bool hasComment(const std::string& str)
    471     {
    472         return (getCommentPosition(str) != std::string::npos);
    473     }
    474 
    475     /**
    476         @brief If the string contains a comment, the comment gets returned (including the comment symbol), an empty string otherwise.
    477         @param str The string
    478         @return The comment
    479     */
    480     std::string getComment(const std::string& str)
    481     {
    482         return str.substr(getCommentPosition(str));
    483     }
    484 
    485     /**
    486         @brief If the string contains a comment, the position of the comment-symbol gets returned, std::string::npos otherwise.
    487         @param str The string
    488         @return The position
    489     */
    490     size_t getCommentPosition(const std::string& str)
    491     {
    492         return getNextCommentPosition(str, 0);
    493     }
    494 
    495     /**
    496         @brief Returns the position of the next comment-symbol, starting with start.
    497         @param str The string
    498         @param start The startposition
    499         @return The position
     453        @param start The first position to look at
    500454    */
    501455    size_t getNextCommentPosition(const std::string& str, size_t start)

  • code/trunk/src/libraries/util/StringUtils.h

    r7284 r7401  
    2828
    2929/**
     30    @defgroup String String functions
     31    @ingroup Util
     32*/
     33
     34/**
    3035    @file
     36    @ingroup String
    3137    @brief Declaration of several string manipulation functions, used in many parts of the game.
    3238*/

  • code/trunk/src/libraries/util/SubString.cc

    r7284 r7401  
    3838 */
    3939
     40/**
     41    @file
     42    @brief Implementation of the SubString class.
     43*/
     44
    4045#include "SubString.h"
    4146#include <cstdio>
     47#include "Debug.h"
    4248
    4349namespace orxonox
    4450{
    45     /**
    46      * @brief default constructor
    47      */
     51    const std::string SubString::WhiteSpaces          = " \n\t";
     52    const std::string SubString::WhiteSpacesWithComma = " \n\t,";
     53    const SubString SubString::NullSubString          = SubString();
     54
     55    /**
     56        @brief Default constructor.
     57    */
    4858    SubString::SubString()
    49     {}
    50 
    51 
    52     /**
    53      * @brief create a SubString from
    54      * @param string the String to Split
    55      * @param delimiter the Character at which to split string (delimiter)
    56      */
    57     SubString::SubString(const std::string& string, char delimiter)
    58     {
    59         this->split(string, delimiter);
    60     }
    61 
    62 
    63     /**
    64      * @brief Splits a String into multiple splitters.
    65      * @param string the String to split
    66      * @param delimiters multiple set of characters at what to split. (delimiters)
    67      * @param delimiterNeighbours neighbours of the delimiters, that will be erased only when near a delimiter.
    68      * @param emptyEntries If empty entries should be allewed or removed.
    69      * @param escapeChar The Escape Character that overrides splitters commends and so on...
    70      * @param safemode_char within these characters splitting won't happen
    71      * @param comment_char the Comment character.
    72      */
    73     SubString::SubString(const std::string& string,
    74                          const std::string& delimiters, const std::string& delimiterNeighbours, bool emptyEntries,
    75                          char escapeChar, bool removeEscapeChar, char safemode_char, bool removeSafemodeChar,
    76                          char openparenthesis_char, char closeparenthesis_char, bool removeParenthesisChars, char comment_char)
    77     {
    78         SubString::splitLine(this->strings, this->bInSafemode, string, delimiters, delimiterNeighbours, emptyEntries, escapeChar, removeEscapeChar, safemode_char, removeSafemodeChar, openparenthesis_char, closeparenthesis_char, removeParenthesisChars, comment_char);
    79     }
    80 
    81     /**
    82      * @brief creates a SubSet of a SubString.
    83      * @param subString the SubString to take a set from.
    84      * @param subSetBegin the beginning to the end
    85      */
    86     SubString::SubString(const SubString& subString, unsigned int subSetBegin)
    87     {
    88         for (unsigned int i = subSetBegin; i < subString.size(); i++)
    89         {
    90             this->strings.push_back(subString[i]);
    91             this->bInSafemode.push_back(subString.isInSafemode(i));
    92         }
    93     }
    94 
    95 
    96     /**
    97      * @brief creates a SubSet of a SubString.
    98      * @param subString the SubString to take a Set from
    99      * @param subSetBegin the beginning to the end
    100      * @param subSetEnd the end of the SubSet (max subString.size() will be checked internaly)
    101      */
    102     SubString::SubString(const SubString& subString, unsigned int subSetBegin, unsigned int subSetEnd)
    103     {
    104         for (unsigned int i = subSetBegin; i < subString.size() && i < subSetEnd; i++)
    105         {
    106             this->strings.push_back(subString[i]);
    107             this->bInSafemode.push_back(subString.isInSafemode(i));
    108         }
    109     }
    110 
    111     /**
    112      * @brief creates a Substring from a count and values set.
    113      * @param argc: the Arguments Count.
    114      * @param argv: Argument Values.
    115      */
     59    {
     60    }
     61
     62    /**
     63        @brief Splits a string into multiple tokens.
     64        @param line The line to split
     65        @param delimiters Multiple characters at which to split the line
     66        @param delimiterNeighbours Neighbours of the delimiters that will be erased as well (for example white-spaces)
     67        @param bAllowEmptyEntries If true, empty tokens are also added to the SubString (if there are two delimiters without a char in between)
     68        @param escapeChar The escape character that is used to escape safemode chars (for example if you want to use a quotation mark between two other quotation marks).
     69        @param bRemoveEscapeChar If true, the escape char is removed from the tokens
     70        @param safemodeChar Within these characters splitting won't happen (usually the quotation marks)
     71        @param bRemoveSafemodeChar Removes the safemodeChar from the beginning and the ending of a token
     72        @param openparenthesisChar The beginning of a safemode is marked with this (usually an opening brace)
     73        @param closeparenthesisChar The ending of a safemode is marked with this (usually a closing brace)
     74        @param bRemoveParenthesisChars Removes the parenthesis chars from the beginning and the ending of a token
     75        @param commentChar The comment character (used to ignore the part of the line after the comment char).
     76    */
     77    SubString::SubString(const std::string& line,
     78                         const std::string& delimiters, const std::string& delimiterNeighbours, bool bAllowEmptyEntries,
     79                         char escapeChar, bool bRemoveEscapeChar, char safemodeChar, bool bRemoveSafemodeChar,
     80                         char openparenthesisChar, char closeparenthesisChar, bool bRemoveParenthesisChars, char commentChar)
     81    {
     82        SubString::splitLine(this->tokens_, this->bTokenInSafemode_, line, delimiters, delimiterNeighbours, bAllowEmptyEntries, escapeChar, bRemoveEscapeChar, safemodeChar, bRemoveSafemodeChar, openparenthesisChar, closeparenthesisChar, bRemoveParenthesisChars, commentChar);
     83    }
     84
     85    /**
     86        @brief creates a new SubString based on a subset of an other SubString.
     87        @param other The other SubString
     88        @param begin The beginning of the subset
     89
     90        The subset ranges from the token with index @a begin to the end of the tokens.
     91        If @a begin is greater than the greatest index, the new SubString will be empty.
     92    */
     93    SubString::SubString(const SubString& other, unsigned int begin)
     94    {
     95        for (unsigned int i = begin; i < other.size(); ++i)
     96        {
     97            this->tokens_.push_back(other[i]);
     98            this->bTokenInSafemode_.push_back(other.isInSafemode(i));
     99        }
     100    }
     101
     102    /**
     103        @brief creates a new SubString based on a subset of an other SubString.
     104        @param other The other SubString
     105        @param begin The beginning of the subset
     106        @param end The end of the subset
     107
     108        The subset ranges from the token with index @a begin until (but not including) the token with index @a end.
     109        If @a begin or @a end are beyond the allowed index, the resulting SubString will be empty.
     110    */
     111    SubString::SubString(const SubString& other, unsigned int begin, unsigned int end)
     112    {
     113        for (unsigned int i = begin; i < std::min(other.size(), end); ++i)
     114        {
     115            this->tokens_.push_back(other[i]);
     116            this->bTokenInSafemode_.push_back(other.isInSafemode(i));
     117        }
     118    }
     119
     120    /**
     121        @brief Creates a SubString from a count and values set.
     122        @param argc The number of arguments
     123        @param argv An array of pointers to the arguments
     124    */
    116125    SubString::SubString(unsigned int argc, const char** argv)
    117126    {
    118127        for(unsigned int i = 0; i < argc; ++i)
    119128        {
    120             this->strings.push_back(std::string(argv[i]));
    121             this->bInSafemode.push_back(false);
    122         }
    123     }
    124 
    125     /**
    126      * @brief removes the object from memory
    127      */
     129            this->tokens_.push_back(std::string(argv[i]));
     130            this->bTokenInSafemode_.push_back(false);
     131        }
     132    }
     133
     134    /**
     135        @brief Destructor
     136    */
    128137    SubString::~SubString()
    129138    { }
    130139
    131     /** @brief An empty String */
    132     // const std::string SubString::emptyString = "";
    133     /** @brief Helper that gets you a String consisting of all White Spaces */
    134     const std::string SubString::WhiteSpaces = " \n\t";
    135     /** @brief Helper that gets you a String consisting of all WhiteSpaces and the Comma */
    136     const std::string SubString::WhiteSpacesWithComma = " \n\t,";
    137     /** An Empty SubString */
    138     const SubString SubString::NullSubString = SubString();
    139 
    140     /**
    141      * @brief stores the Value of subString in this SubString
    142      * @param subString will be copied into this String.
    143      * @returns this SubString.
    144      */
    145     SubString& SubString::operator=(const SubString& subString)
    146     {
    147         this->strings = subString.strings;
    148         this->bInSafemode = subString.bInSafemode;
     140    /**
     141        @brief Stores the tokens of @a other in this SubString
     142        @return This SubString.
     143    */
     144    SubString& SubString::operator=(const SubString& other)
     145    {
     146        this->tokens_ = other.tokens_;
     147        this->bTokenInSafemode_ = other.bTokenInSafemode_;
    149148        return *this;
    150149    }
    151150
    152 
    153     /**
    154      * @brief comparator.
    155      * @param subString the SubString to compare against this one.
    156      * @returns true if the Stored Strings match
    157      */
    158     bool SubString::operator==(const SubString& subString) const
    159     {
    160         return ((this->strings == subString.strings) && (this->bInSafemode == subString.bInSafemode));
    161     }
    162 
    163     /**
    164      * @brief comparator.
    165      * @param subString the SubString to compare against this one.
    166      * @returns true if the Stored Strings match
    167      */
    168     bool SubString::compare(const SubString& subString) const
    169     {
    170         return (*this == subString);
    171     }
    172 
    173     /**
    174      * @brief comparator.
    175      * @param subString the SubString to compare against this one.
    176      * @param length how many entries to compare. (from 0 to length)
    177      * @returns true if the Stored Strings match
    178      */
    179     bool SubString::compare(const SubString& subString, unsigned int length) const
    180     {
    181         if (length > this->size() || length > subString.size())
     151    /**
     152        @brief Compares this SubString to another SubString and returns true if they contain the same values.
     153    */
     154    bool SubString::operator==(const SubString& other) const
     155    {
     156        return ((this->tokens_ == other.tokens_) && (this->bTokenInSafemode_ == other.bTokenInSafemode_));
     157    }
     158
     159    /**
     160        @copydoc operator==
     161    */
     162    bool SubString::compare(const SubString& other) const
     163    {
     164        return (*this == other);
     165    }
     166
     167    /**
     168        @brief Compares this SubString to another SubString and returns true if the first @a length values match.
     169        @param other The other SubString
     170        @param length How many tokens to compare
     171    */
     172    bool SubString::compare(const SubString& other, unsigned int length) const
     173    {
     174        if (length > this->size() || length > other.size())
    182175            return false;
    183176
    184         for (unsigned int i = 0; i < length; i++)
    185             if ((this->strings[i] != subString.strings[i]) || (this->bInSafemode[i] != subString.bInSafemode[i]))
     177        for (unsigned int i = 0; i < length; ++i)
     178            if ((this->tokens_[i] != other.tokens_[i]) || (this->bTokenInSafemode_[i] != other.bTokenInSafemode_[i]))
    186179                return false;
    187180        return true;
    188181    }
    189182
    190 
    191     /**
    192      * @brief append operator
    193      * @param subString the String to append.
    194      * @returns a SubString where this and subString are appended.
    195      */
    196     SubString SubString::operator+(const SubString& subString) const
    197     {
    198         return SubString(*this) += subString;
    199     }
    200 
    201 
    202     /**
    203      * @brief append operator.
    204      * @param subString append subString to this SubString.
    205      * @returns this substring appended with subString
    206      */
    207     SubString& SubString::operator+=(const SubString& subString)
    208     {
    209         for (unsigned int i = 0; i < subString.size(); i++)
    210         {
    211             this->strings.push_back(subString[i]);
    212             this->bInSafemode.push_back(subString.isInSafemode(i));
     183    /**
     184        @brief Concatenates the tokens of two SubStrings and returns the resulting new SubString
     185        @return A new SubString that contains the tokens of this and the other SubString
     186    */
     187    SubString SubString::operator+(const SubString& other) const
     188    {
     189        return SubString(*this) += other;
     190    }
     191
     192    /**
     193        @brief Appends the tokens of @a other to this SubString
     194        @return This SubString
     195    */
     196    SubString& SubString::operator+=(const SubString& other)
     197    {
     198        for (unsigned int i = 0; i < other.size(); ++i)
     199        {
     200            this->tokens_.push_back(other[i]);
     201            this->bTokenInSafemode_.push_back(other.isInSafemode(i));
    213202        }
    214203        return *this;
    215204    }
    216205
    217 
    218     /**
    219      * @brief Split the String at
    220      * @param string where to split
    221      * @param splitter delimiter.
    222      */
    223     unsigned int SubString::split(const std::string& string, char splitter)
    224     {
    225         this->strings.clear();
    226         this->bInSafemode.clear();
    227         char split[2];
    228         split[0] = splitter;
    229         split[1] = '\0';
    230         SubString::splitLine(this->strings, this->bInSafemode, string, split);
    231         return strings.size();
    232     }
    233 
    234 
    235     /**
    236      * @brief Splits a String into multiple splitters.
    237      * @param string the String to split
    238      * @param delimiters multiple set of characters at what to split. (delimiters)
    239      * @param delimiterNeighbours: Neighbours to the Delimiters that will be erased too.
    240      * @param emptyEntries: If empty entries are added to the List of SubStrings
    241      * @param escapeChar The Escape Character that overrides splitters commends and so on...
    242      * @param safemode_char within these characters splitting won't happen
    243      * @param comment_char the Comment character.
    244      */
    245     unsigned int SubString::split(const std::string& string,
    246                                   const std::string& delimiters, const std::string& delimiterNeighbours, bool emptyEntries,
    247                                   char escapeChar, bool removeExcapeChar, char safemode_char, bool removeSafemodeChar,
    248                                   char openparenthesis_char, char closeparenthesis_char, bool removeParenthesisChars, char comment_char)
    249     {
    250         this->strings.clear();
    251         this->bInSafemode.clear();
    252         SubString::splitLine(this->strings, this->bInSafemode, string, delimiters, delimiterNeighbours, emptyEntries, escapeChar, removeExcapeChar, safemode_char, removeSafemodeChar, openparenthesis_char, closeparenthesis_char, removeParenthesisChars, comment_char);
    253         return this->strings.size();
    254     }
    255 
    256 
    257     /**
    258      * @brief joins together all Strings of this Substring.
    259      * @param delimiter the String between the subStrings.
    260      * @returns the joined String.
    261      */
     206    /**
     207        @copydoc SubString(const std::string&,const std::string&,const std::string&,bool,char,bool,char,bool,char,char,bool,char)
     208    */
     209    unsigned int SubString::split(const std::string& line,
     210                                  const std::string& delimiters, const std::string& delimiterNeighbours, bool bAllowEmptyEntries,
     211                                  char escapeChar, bool bRemoveEscapeChar, char safemodeChar, bool bRemoveSafemodeChar,
     212                                  char openparenthesisChar, char closeparenthesisChar, bool bRemoveParenthesisChars, char commentChar)
     213    {
     214        this->tokens_.clear();
     215        this->bTokenInSafemode_.clear();
     216        SubString::splitLine(this->tokens_, this->bTokenInSafemode_, line, delimiters, delimiterNeighbours, bAllowEmptyEntries, escapeChar, bRemoveEscapeChar, safemodeChar, bRemoveSafemodeChar, openparenthesisChar, closeparenthesisChar, bRemoveParenthesisChars, commentChar);
     217        return this->tokens_.size();
     218    }
     219
     220    /**
     221        @brief Joins the tokens of this SubString using the given delimiter and returns a string.
     222        @param delimiter This delimiter will be placed between each two tokens
     223        @return The joined string.
     224    */
    262225    std::string SubString::join(const std::string& delimiter) const
    263226    {
    264         if (!this->strings.empty())
    265         {
    266             std::string retVal = this->strings[0];
    267             for (unsigned int i = 1; i < this->strings.size(); i++)
    268                 retVal += delimiter + this->strings[i];
     227        if (!this->tokens_.empty())
     228        {
     229            std::string retVal = this->tokens_[0];
     230            for (unsigned int i = 1; i < this->tokens_.size(); ++i)
     231                retVal += delimiter + this->tokens_[i];
    269232            return retVal;
    270233        }
    … …  
    273236    }
    274237
    275 
    276     /**
    277      * @brief creates a SubSet of a SubString.
    278      * @param subSetBegin the beginning to the end
    279      * @returns the SubSet
    280      *
    281      * This function is added for your convenience, and does the same as
    282      * SubString::SubString(const SubString& subString, unsigned int subSetBegin)
    283      */
    284     SubString SubString::subSet(unsigned int subSetBegin) const
    285     {
    286         return SubString(*this, subSetBegin);
    287     }
    288 
    289 
    290     /**
    291      * @brief creates a SubSet of a SubString.
    292      * @param subSetBegin the beginning to
    293      * @param subSetEnd the end of the SubSet to select (if bigger than subString.size() it will be downset.)
    294      * @returns the SubSet
    295      *
    296      * This function is added for your convenience, and does the same as
    297      * SubString::SubString(const SubString& subString, unsigned int subSetBegin)
    298      */
    299     SubString SubString::subSet(unsigned int subSetBegin, unsigned int subSetEnd) const
    300     {
    301         return SubString(*this, subSetBegin, subSetEnd);
    302     }
    303 
    304 
    305     /**
    306      * @brief splits line into tokens and stores them in ret.
    307      * @param ret the Array, where the Splitted strings will be stored in
    308      * to the beginning of the current token is stored
    309      * @param line the inputLine to split
    310      * @param delimiters a String of Delimiters (here the input will be splitted)
    311      * @param delimiterNeighbours Neighbours to the Delimiter, that will be removed if they are to the left or the right of a Delimiter.
    312      * @param emptyEntries: if empty Strings are added to the List of Strings.
    313      * @param escape_char: Escape carater (escapes splitters)
    314      * @param safemode_char: the beginning of the safemode is marked with this
    315      * @param removeSafemodeChar removes the safemode_char from the beginning and the ending of a token
    316      * @param openparenthesis_char the beginning of a safemode is marked with this
    317      * @param closeparenthesis_char the ending of a safemode is marked with this
    318      * @param removeParenthesisChars removes the parenthesis from the beginning and the ending of a token
    319      * @param comment_char: the beginning of a comment is marked with this: (until the end of a Line)
    320      * @param start_state: the Initial state on how to parse the String.
    321      * @return SPLIT_LINE_STATE the parser was in when returning
    322      *
    323      * This is the Actual Splitting Algorithm from Clemens Wacha
    324      * Supports delimiters, escape characters,
    325      * ignores special  characters between safemode_char and between comment_char and linend '\n'.
    326      */
     238    /**
     239        @brief Creates a subset of this SubString.
     240        @param begin The beginning of the subset
     241        @return A new SubString containing the defined subset.
     242
     243        The subset ranges from the token with index @a begin to the end of the tokens.
     244        If @a begin is greater than the greatest index, the new SubString will be empty.
     245
     246        This function is added for your convenience, and does the same as
     247        SubString::SubString(const SubString& other, unsigned int begin)
     248    */
     249    SubString SubString::subSet(unsigned int begin) const
     250    {
     251        return SubString(*this, begin);
     252    }
     253
     254    /**
     255        @brief Creates a subset of this SubString.
     256        @param begin The beginning of the subset
     257        @param end The ending of the subset
     258        @return A new SubString containing the defined subset.
     259
     260        The subset ranges from the token with index @a begin until (but not including) the token with index @a end.
     261        If @a begin or @a end are beyond the allowed index, the resulting SubString will be empty.
     262
     263        This function is added for your convenience, and does the same as
     264        SubString::SubString(const SubString& other, unsigned int begin, unsigned int end)
     265    */
     266    SubString SubString::subSet(unsigned int begin, unsigned int end) const
     267    {
     268        return SubString(*this, begin, end);
     269    }
     270
     271    /**
     272        @copydoc SubString(const std::string&,const std::string&,const std::string&,bool,char,bool,char,bool,char,char,bool,char)
     273        @param tokens The array, where the splitted strings will be stored in
     274        @param bTokenInSafemode A vector wich stores for each character of the string if it is in safemode or not
     275        @param start_state The internal state of the parser
     276
     277        This is the actual splitting algorithm from Clemens Wacha.
     278        Supports delimiters, escape characters, ignores special characters between safemodeChar and between commentChar and line end "\n".
     279
     280        Extended by Orxonox to support parenthesis as additional safe-mode.
     281    */
    327282    SubString::SPLIT_LINE_STATE
    328     SubString::splitLine(std::vector<std::string>& ret,
    329                          std::vector<bool>& bInSafemode,
     283    SubString::splitLine(std::vector<std::string>& tokens,
     284                         std::vector<bool>& bTokenInSafemode,
    330285                         const std::string& line,
    331286                         const std::string& delimiters,
    332287                         const std::string& delimiterNeighbours,
    333                          bool emptyEntries,
    334                          char escape_char,
    335                          bool removeExcapeChar,
    336                          char safemode_char,
    337                          bool removeSafemodeChar,
    338                          char openparenthesis_char,
    339                          char closeparenthesis_char,
    340                          bool removeParenthesisChars,
    341                          char comment_char,
     288                         bool bAllowEmptyEntries,
     289                         char escapeChar,
     290                         bool bRemoveEscapeChar,
     291                         char safemodeChar,
     292                         bool bRemoveSafemodeChar,
     293                         char openparenthesisChar,
     294                         char closeparenthesisChar,
     295                         bool bRemoveParenthesisChars,
     296                         char commentChar,
    342297                         SPLIT_LINE_STATE start_state)
    343298    {
    … …  
    349304        bool inSafemode = false;
    350305
    351         if(start_state != SL_NORMAL && ret.size() > 0)
    352         {
    353             token = ret[ret.size()-1];
    354             ret.pop_back();
    355         }
    356         if(start_state != SL_NORMAL && bInSafemode.size() > 0)
    357         {
    358             inSafemode = bInSafemode[bInSafemode.size()-1];
    359             bInSafemode.pop_back();
     306        if(start_state != SL_NORMAL && tokens.size() > 0)
     307        {
     308            token = tokens[tokens.size()-1];
     309            tokens.pop_back();
     310        }
     311        if(start_state != SL_NORMAL && bTokenInSafemode.size() > 0)
     312        {
     313            inSafemode = bTokenInSafemode[bTokenInSafemode.size()-1];
     314            bTokenInSafemode.pop_back();
    360315        }
    361316
    … …  
    365320            {
    366321            case SL_NORMAL:
    367                 if(line[i] == escape_char)
     322                if(line[i] == escapeChar)
    368323                {
    369324                    state = SL_ESCAPE;
    370                     if (!removeExcapeChar)
     325                    if (!bRemoveEscapeChar)
    371326                        token += line[i];
    372                 }
    373                 else if(line[i] == safemode_char)
     327                    fallBackNeighbours = 0;
     328                }
     329                else if(line[i] == safemodeChar)
    374330                {
    375331                    state = SL_SAFEMODE;
    376332                    inSafemode = true;
    377                     if (!removeSafemodeChar)
     333                    if (!bRemoveSafemodeChar)
    378334                        token += line[i];
    379                 }
    380                 else if(line[i] == openparenthesis_char)
     335                    fallBackNeighbours = 0;
     336                }
     337                else if(line[i] == openparenthesisChar)
    381338                {
    382339                    state = SL_PARENTHESES;
    383340                    inSafemode = true;
    384                     if (!removeParenthesisChars)
     341                    if (!bRemoveParenthesisChars)
    385342                        token += line[i];
    386                 }
    387                 else if(line[i] == comment_char)
     343                    fallBackNeighbours = 0;
     344                }
     345                else if(line[i] == commentChar)
    388346                {
    389347                    if (fallBackNeighbours > 0)
    390348                        token = token.substr(0, token.size() - fallBackNeighbours);
    391                     /// FINISH
    392                     if(emptyEntries || token.size() > 0)
     349                    fallBackNeighbours = 0;
     350                    // FINISH
     351                    if(bAllowEmptyEntries || token.size() > 0)
    393352                    {
    394                         ret.push_back(token);
     353                        tokens.push_back(token);
    395354                        token.clear();
    396                         bInSafemode.push_back(inSafemode);
     355                        bTokenInSafemode.push_back(inSafemode);
    397356                        inSafemode = false;
    398357                    }
    … …  
    405364                    if (fallBackNeighbours > 0)
    406365                        token = token.substr(0, token.size() - fallBackNeighbours);
    407                     /// FINISH
    408                     if(emptyEntries || token.size() > 0)
     366                    fallBackNeighbours = 0;
     367                    // FINISH
     368                    if(bAllowEmptyEntries || token.size() > 0)
    409369                    {
    410                         ret.push_back(token);
     370                        tokens.push_back(token);
    411371                        token.clear();
    412                         bInSafemode.push_back(inSafemode);
     372                        bTokenInSafemode.push_back(inSafemode);
    413373                        inSafemode = false;
    414374                    }
    … …  
    423383                        else
    424384                        {
    425                             i++;
     385                            ++i;
    426386                            continue;
    427387                        }
    … …  
    433393                break;
    434394            case SL_ESCAPE:
    435                 if (!removeSafemodeChar)
     395                if (!bRemoveSafemodeChar)
    436396                    token += line[i];
    437397                else
    … …  
    450410                break;
    451411            case SL_SAFEMODE:
    452                 if(line[i] == safemode_char)
     412                if(line[i] == safemodeChar)
    453413                {
    454414                    state = SL_NORMAL;
    455                     if (!removeSafemodeChar)
     415                    if (!bRemoveSafemodeChar)
    456416                        token += line[i];
    457417                }
    458                 else if(line[i] == escape_char)
     418                else if(line[i] == escapeChar)
    459419                {
    460420                    state = SL_SAFEESCAPE;
    … …  
    480440
    481441            case SL_PARENTHESES:
    482                 if(line[i] == closeparenthesis_char)
     442                if(line[i] == closeparenthesisChar)
    483443                {
    484444                    state = SL_NORMAL;
    485                     if (!removeParenthesisChars)
     445                    if (!bRemoveParenthesisChars)
    486446                        token += line[i];
    487447                }
    488                 else if(line[i] == escape_char)
     448                else if(line[i] == escapeChar)
    489449                {
    490450                    state = SL_PARENTHESESESCAPE;
    … …  
    512472                if(line[i] == '\n')
    513473                {
    514                     /// FINISH
     474                    // FINISH
    515475                    if(token.size() > 0)
    516476                    {
    517                         ret.push_back(token);
     477                        tokens.push_back(token);
    518478                        token.clear();
    519                         bInSafemode.push_back(inSafemode);
     479                        bTokenInSafemode.push_back(inSafemode);
    520480                        inSafemode = false;
    521481                    }
    … …  
    532492                break;
    533493            }
    534             i++;
    535         }
    536 
    537         /// FINISH
     494            ++i;
     495        }
     496
     497        // FINISH
    538498        if (fallBackNeighbours > 0)
    539499            token = token.substr(0, token.size() - fallBackNeighbours);
    540         if(emptyEntries || token.size() > 0)
    541         {
    542             ret.push_back(token);
     500        if(bAllowEmptyEntries || token.size() > 0)
     501        {
     502            tokens.push_back(token);
    543503            token.clear();
    544             bInSafemode.push_back(inSafemode);
     504            bTokenInSafemode.push_back(inSafemode);
    545505            inSafemode = false;
    546506        }
    … …  
    548508    }
    549509
    550 
    551     /**
    552      * @brief Some nice debug information about this SubString
    553      */
     510    /**
     511        @brief Some nice debug information about this SubString.
     512    */
    554513    void SubString::debug() const
    555514    {
    556         printf("Substring-information::count=%d ::", this->strings.size());
    557         for (unsigned int i = 0; i < this->strings.size(); i++)
    558             printf("s%d='%s'::", i, this->strings[i].c_str());
    559         printf("\n");
     515        COUT(0) << "Substring-information::count=" << this->tokens_.size() << " ::";
     516        for (unsigned int i = 0; i < this->tokens_.size(); ++i)
     517            COUT(0) << "s" << i << "='" << this->tokens_[i].c_str() << "'::";
     518        COUT(0) << std::endl;
    560519    }
    561520}

  • code/trunk/src/libraries/util/SubString.h

    r7284 r7401  
    3737 */
    3838
    39  /*!
    40  * @file
    41  * @brief a small class to get the parts of a string separated by commas
    42  *
    43  * This class is also identified as a Tokenizer. It splits up one long
    44  * String into multiple small ones by a designated Delimiter.
    45  *
    46  * Substring is Advanced, and it is possible, to split a string by ','
    47  * but also removing leading and trailing spaces around the comma.
    48  *
    49  * @example
    50  * Split the String std::string st = "1345, The new empire   , is , orxonox"
    51  * is splitted with:
    52  * SubString(st, ',', " \n\t")
    53  * into
    54  * "1345", "The new empire", "is", "orxonox"
    55  * As you can see, the useless spaces around ',' were removed.
    56  */
     39 /**
     40    @file
     41    @ingroup String
     42    @brief A helper class to split a string into several tokens.
     43
     44    @anchor SubStringExample
     45
     46    The class SubString can be used to split an std::string into multiple tokens, using
     47    a delimiter. SubString allows different options, for example to remove whitespaces
     48    around the delimiters or different safe-mode chars, like quotation marks and braces.
     49
     50    You can access the tokens of the SubString using the [] operator like an array.
     51    SubString also supports to join the tokens (or a subset of the tokens) again using
     52    @ref orxonox::SubString::join() "join()". It's even possible to get a subset of the
     53    SubString as another SubString using @ref orxonox::SubString::subSet() "subSet()".
     54
     55    Example:
     56    @code
     57    std::string text = "This is a test, \"Hello \\\" World\" and vector {1, 2, 3}";
     58    SubString tokens(text, SubString::WhiteSpaces, "", false, '\\', true, '"', true, '{', '}', true, '\0');
     59
     60    for (unsigned int i = 0; i < tokens.size(); ++i)
     61        COUT(0) << i << ": " << tokens[i] << std::endl;
     62    @endcode
     63
     64    The output of this code is:
     65     - 0: This
     66     - 1: is
     67     - 2: a
     68     - 3: test,
     69     - 4: Hello " World
     70     - 5: and
     71     - 6: vector
     72     - 7: 1, 2, 3
     73
     74    The string was split using the delimiter " ". A string between quotation mark is not
     75    split, the same holds for strings between '{' and '}'. Note how the quotation marks and
     76    the braces were removed from the tokens, because the corresponding argument is 'true'.
     77
     78    Also note that the comma after "test" in token 3 is still there - it is neither part of the
     79    delimiters SubString::WhiteSpaces nor part of the delimiterNeighbours parameter, so it
     80    remains a part of the token.
     81*/
    5782
    5883#ifndef __SubString_H__
    … …  
    6691namespace orxonox
    6792{
    68     //! A class that can load one string and split it in multipe ones
    6993    /**
    70      * SubString is a very Powerfull way to create a SubSet from a String
    71      * It can be used, to Split strings append them and join them again.
    72      */
     94        @brief A class that splits a string into multiple tokens using different options.
     95
     96        The string is split into multiple tokens using a delimiter. Different options like
     97        escape character, quotation marks, and more can be used to satisfy your needs.
     98
     99        See @ref SubStringExample "this description" for an example.
     100    */
    73101    class _UtilExport SubString
    74102    {
    75     public:
    76         //! An enumerator for the State the Parser is in
    77         typedef enum {
     103        /// An enumerator for the internal state of the parser
     104        enum SPLIT_LINE_STATE
     105        {
    78106            SL_NORMAL,            //!< Normal state
    79107            SL_ESCAPE,            //!< After an escape character
    80             SL_SAFEMODE,          //!< In safe mode (between "" mostly).
     108            SL_SAFEMODE,          //!< In safe mode (usually between quotation marks).
    81109            SL_SAFEESCAPE,        //!< In safe mode with the internal escape character, that escapes even the savemode character.
    82110            SL_COMMENT,           //!< In Comment mode.
    83111            SL_PARENTHESES,       //!< Between parentheses (usually '{' and '}')
    84112            SL_PARENTHESESESCAPE, //!< Between parentheses with the internal escape character, that escapes even the closing paranthesis character.
    85         } SPLIT_LINE_STATE;
    86 
     113        };
    87114
    88115    public:
    89116        SubString();
    90         SubString(const std::string& string, char delimiter = ',');
    91         SubString(const std::string& string,
    92                   const std::string& delimiters, const std::string& delimiterNeighbours = "", bool emptyEntries=false,
    93                   char escapeChar ='\\', bool removeEscapeChar = true, char safemode_char = '"', bool removeSafemodeChar = true,
    94                   char openparenthesis_char = '{', char closeparenthesis_char = '}',  bool removeParenthesisChars = true, char comment_char = '\0');
     117        SubString(const std::string& line,
     118                  const std::string& delimiters = SubString::WhiteSpaces,
     119                  const std::string& delimiterNeighbours = "",
     120                  bool bAllowEmptyEntries=false,
     121                  char escapeChar ='\\',
     122                  bool bRemoveEscapeChar = true,
     123                  char safemodeChar = '"',
     124                  bool bRemoveSafemodeChar = true,
     125                  char openparenthesisChar = '{',
     126                  char closeparenthesisChar = '}',
     127                  bool bRemoveParenthesisChars = true,
     128                  char commentChar = '\0');
    95129        SubString(unsigned int argc, const char** argv);
    96         /** @brief create a Substring as a copy of another one. @param subString the SubString to copy. */
    97         SubString(const SubString& subString) { *this = subString; };
    98         SubString(const SubString& subString, unsigned int subSetBegin);
    99         SubString(const SubString& subString, unsigned int subSetBegin, unsigned int subSetEnd);
     130        SubString(const SubString& other, unsigned int begin);
     131        SubString(const SubString& other, unsigned int begin, unsigned int end);
    100132        ~SubString();
    101133
    102134        // operate on the SubString
    103         SubString& operator=(const SubString& subString);
    104         bool operator==(const SubString& subString) const;
    105         bool compare(const SubString& subString) const;
    106         bool compare(const SubString& subString, unsigned int length) const;
    107         SubString operator+(const SubString& subString) const;
    108         SubString& operator+=(const SubString& subString);
    109         /** @param subString the String to append @returns appended String. @brief added for convenience */
    110         SubString& append(const SubString subString) { return (*this += subString); };
     135        SubString& operator=(const SubString& other);
     136        bool operator==(const SubString& other) const;
     137        bool compare(const SubString& other) const;
     138        bool compare(const SubString& other, unsigned int length) const;
     139        SubString operator+(const SubString& other) const;
     140        SubString& operator+=(const SubString& other);
     141        /// Appends the tokens of another SubString to this. @return This SubString.
     142        inline SubString& append(const SubString& other) { return (*this += other); }
    111143
    112144        /////////////////////////////////////////
    113145        // Split and Join the any String. ///////
    114         unsigned int split(const std::string& string = "", char delimiter = ',');
    115         unsigned int split(const std::string& string,
    116                            const std::string& delimiters, const std::string& delimiterNeighbours = "", bool emptyEntries = false,
    117                            char escapeChar ='\\', bool removeExcapeChar = true, char safemode_char = '"', bool removeSafemodeChar = true,
    118                            char openparenthesis_char = '{', char closeparenthesis_char = '}',  bool removeParenthesisChars = true, char comment_char = '\0');
     146        unsigned int split(const std::string& line,
     147                           const std::string& delimiters = SubString::WhiteSpaces,
     148                           const std::string& delimiterNeighbours = "",
     149                           bool bAllowEmptyEntries = false,
     150                           char escapeChar ='\\',
     151                           bool bRemoveEscapeChar = true,
     152                           char safemodeChar = '"',
     153                           bool bRemoveSafemodeChar = true,
     154                           char openparenthesisChar = '{',
     155                           char closeparenthesisChar = '}',
     156                           bool bRemoveParenthesisChars = true,
     157                           char commentChar = '\0');
     158
    119159        std::string join(const std::string& delimiter = " ") const;
    120160        ////////////////////////////////////////
    121161
    122162        // retrieve a SubSet from the String
    123         SubString subSet(unsigned int subSetBegin) const;
    124         SubString subSet(unsigned int subSetBegin, unsigned int subSetEnd) const;
     163        SubString subSet(unsigned int begin) const;
     164        SubString subSet(unsigned int begin, unsigned int end) const;
    125165
    126166        // retrieve Information from within
    127         /** @brief Returns true if the SubString is empty */
    128         inline bool empty() const { return this->strings.empty(); };
    129         /** @brief Returns the count of Strings stored in this substring */
    130         inline unsigned int size() const { return this->strings.size(); };
    131         /** @brief Returns the i'th string from the subset of Strings @param i the i'th String */
    132         inline const std::string& operator[](unsigned int i) const { return this->strings[i]; };
    133         /** @brief Returns the i'th string from the subset of Strings @param i the i'th String */
    134         inline const std::string& getString(unsigned int i) const { return (*this)[i]; };
    135         /** @brief Returns all Strings as std::vector */
    136         inline const std::vector<std::string>& getAllStrings() const { return this->strings; }
    137         /** @brief Returns true if the token is in safemode. @param i the i'th token */
    138         inline bool isInSafemode(unsigned int i) const { return this->bInSafemode[i]; }
    139         /** @brief Returns the front of the StringList. */
    140         inline const std::string& front() const { return this->strings.front(); };
    141         /** @brief Returns the back of the StringList. */
    142         inline const std::string& back() const { return this->strings.back(); };
    143         /** @brief removes the back of the strings list. */
    144         inline void pop_back() { this->strings.pop_back(); this->bInSafemode.pop_back(); };
    145 
     167        /// Returns true if the SubString is empty
     168        inline bool empty() const { return this->tokens_.empty(); }
     169        /// Returns the number of tokens stored in this SubString
     170        inline unsigned int size() const { return this->tokens_.size(); }
     171        /// Returns the i'th token from the subset of strings @param index The index of the requested doken
     172        inline const std::string& operator[](unsigned int index) const { return this->tokens_[index]; }
     173        /// Returns the i'th token from the subset of strings @param index The index of the requested token
     174        inline const std::string& getString(unsigned int index) const { return (*this)[index]; }
     175        /// Returns all tokens as std::vector
     176        inline const std::vector<std::string>& getAllStrings() const { return this->tokens_; }
     177        /// Returns true if the token is in safemode. @param index The index of the token
     178        inline bool isInSafemode(unsigned int index) const { return this->bTokenInSafemode_[index]; }
     179        /// Returns the front of the list of tokens.
     180        inline const std::string& front() const { return this->tokens_.front(); }
     181        /// Returns the back of the list of tokens.
     182        inline const std::string& back() const { return this->tokens_.back(); }
     183        /// Removes the back of the list of tokens.
     184        inline void pop_back() { this->tokens_.pop_back(); this->bTokenInSafemode_.pop_back(); }
     185
     186        void debug() const;
     187
     188    public:
     189        static const std::string WhiteSpaces;           ///< All whitespaces (usually used as delimiters or delimiterNeighbours
     190        static const std::string WhiteSpacesWithComma;  ///< All whitespaces and the comma (usually used as delimiters)
     191        static const SubString   NullSubString;         ///< An empty SubString
     192
     193    private:
    146194        // the almighty algorithm.
    147         static SPLIT_LINE_STATE splitLine(std::vector<std::string>& ret,
    148                                           std::vector<bool>& bInSafemode,
     195        static SPLIT_LINE_STATE splitLine(std::vector<std::string>& tokens,
     196                                          std::vector<bool>& bTokenInSafemode,
    149197                                          const std::string& line,
    150198                                          const std::string& delimiters = SubString::WhiteSpaces,
    151199                                          const std::string& delimiterNeighbours = "",
    152                                           bool emptyEntries = false,
    153                                           char escape_char = '\\',
    154                                           bool removeExcapeChar = true,
    155                                           char safemode_char = '"',
    156                                           bool removeSafemodeChar = true,
    157                                           char openparenthesis_char = '{',
    158                                           char closeparenthesis_char = '}',
    159                                           bool removeParenthesisChars = true,
    160                                           char comment_char = '\0',
     200                                          bool bAllowEmptyEntries = false,
     201                                          char escapeChar = '\\',
     202                                          bool bRemoveEscapeChar = true,
     203                                          char safemodeChar = '"',
     204                                          bool bRemoveSafemodeChar = true,
     205                                          char openparenthesisChar = '{',
     206                                          char closeparenthesisChar = '}',
     207                                          bool bRemoveParenthesisChars = true,
     208                                          char commentChar = '\0',
    161209                                          SPLIT_LINE_STATE start_state = SL_NORMAL);
    162         // debugging.
    163         void debug() const;
    164 
    165     public:
    166         static const std::string WhiteSpaces;
    167         static const std::string WhiteSpacesWithComma;
    168         static const SubString   NullSubString;
    169 
    170     private:
    171         std::vector<std::string>  strings;                      //!< strings produced from a single string splitted in multiple strings
    172         std::vector<bool>         bInSafemode;
     210
     211        std::vector<std::string>  tokens_;              ///< The tokens after spliting the input line
     212        std::vector<bool>         bTokenInSafemode_;    ///< Saves for each token if it was in safe mode (between quotation marks or parenthesis)
    173213    };
    174214}

  • code/trunk/src/libraries/util/TriBool.h

    r6746 r7401  
    2727 */
    2828
     29/**
     30    @file
     31    @ingroup Util
     32*/
     33
    2934#ifndef _TriBool_H__
    3035#define _TriBool_H__
    … …  
    3540namespace orxonox
    3641{
     42    /** Sort of a boolean value that also has state \c Dontcare
     43    @remarks
     44        Even though \c False has the value 0, both \c True and \c Dontcare have
     45        a value other than 0. Keep that in mind when using TriBools in if statements.
     46    */
    3747    namespace TriBool
    3848    {

  • code/trunk/src/libraries/util/VA_NARGS.h

    r7284 r7401  
    2929/**
    3030    @file
     31    @ingroup Util
    3132    @brief Declaration of the ORXONOX_VA_NARGS macro which returns the number of arguments passed to a variadic macro.
     33
     34    With this utility you can overload a macro for different numbers of arguments
     35    (of course overloading is not possible for different types, as macros are not
     36    type aware, but for different numbers of arguments is still very powerful).
     37
     38    Example: A macro to call functions
     39    @code
     40    myfunction();                                           // A static function
     41    MyClass::myStaticFunction();                            // A static class function
     42    MyClass::myFunction();                                  // A member function
     43
     44    #define CallFunction(...) \                             // Define a variadic macro that passes the arguments to the overloaded implementations
     45        BOOST_PP_EXPAND(BOOST_PP_CAT(CallFunction, ORXONOX_VA_NARGS(__VA_ARGS__))(__VA_ARGS__))
     46
     47    #define CallFunction1(function) \                       // Overloaded macro for 1 argument
     48        function()                                          // Calls the static function
     49
     50    #define CallFunction2(class, function) \                // Overloaded macro for 2 arguments
     51        class::function()                                   // Calls the static class function
     52
     53    #define CallFunction3(class, function, object) \        // Overloaded macro for 3 arguments
     54        object->class::function()                           // Calls the function on the object
     55
     56
     57    CallFunction(myFunction);                               // Call the macro with 1 argument
     58    CallFunction(MyClass, myStaticFunction);                // Call the macro with 2 arguments
     59    CallFunction(MyClass, myFunction, new MyClass());       // Call the macro with 3 arguments
     60    @endcode
     61
     62    Note that the first (variadic) macro concatenates the name "CallFunction" with
     63    the number of arguments ("1" - "N"). Then all arguments are passed to the right macro.
    3264*/
    3365

  • code/trunk/src/libraries/util/mbool.h

    r7268 r7401  
    2727 */
    2828
     29/**
     30    @file
     31    @ingroup Util
     32    @brief Declaration and implementation of the @ref orxonox::mbool class.
     33*/
     34
    2935#ifndef _mbool_H__
    3036#define _mbool_H__
    … …  
    3440namespace orxonox
    3541{
     42    /**
     43        @brief mbool is a small helper class that acts like a bool, but keeps track of the number of its state changes.
     44
     45        The mbool class acts like a bool, but it has an internal counter that counts
     46        the number state changes (i.e. when the bool changes from true to false or
     47        back). This is used in the network if a boolean value is synchronized, because
     48        if a value changes quickly from false to true and back in the same tick, the
     49        clients will never be notified of this action. By using mbool however this
     50        behaviour is fixed, which is important for triggers and other objects.
     51
     52        @note This is efficiently solved by using a union that combines a counter and a
     53        boolean bitfield of size 1. The boolean value corresponds always to the first
     54        bit of the counter - this means, if the counter is incremented, the boolean state
     55        changes. On the other hand, if you want to change the state, you can simply increase
     56        the counter.
     57    */
    3658    struct _UtilExport mbool
    3759    {
    3860        public:
     61            /// Constructor: Creates the mbool and initializes the boolean value (default to false).
    3962            inline mbool(bool value = false)
    4063                { this->value_.memory_ = 0; this->value_.bool_ = value; }
     64            /// Copy-constructor, copies state and memory.
    4165            inline mbool(const mbool& value)
    4266                { this->value_.memory_ = value.value_.memory_; }
    4367
     68            /// Assigns a boolean value (and increases the memory value if the value is different to the old value).
    4469            inline mbool& operator=(bool value)
    4570                { if (value != this->value_.bool_) { ++this->value_.memory_; } return (*this); }
     71            /// Assigns another mbool, copies state and memory.
    4672            inline mbool& operator=(const mbool& value)
    4773                { this->value_.memory_ = value.value_.memory_; return (*this); }
    4874
     75            /// Increases the memory which also inverts it's state (++mbool).
    4976            inline mbool& operator++()
    5077                { ++this->value_.memory_; return (*this); }
    51             inline mbool operator++(int i)
     78            /// Increases the memory which also inverts it's state (mbool++).
     79            inline mbool operator++(int)
    5280                { mbool temp = (*this); ++this->value_.memory_; return temp; }
    5381
     82            /// Implicitly converts the mbool to a bool.
    5483            inline operator bool() const
    5584                { return this->value_.bool_; }
    5685
     86            /// Compares the mbool to a bool, returns true if the bool has the same value as the state of the mbool.
    5787            inline bool operator==(bool other) const
    5888                { return this->value_.bool_ == other; }
     89            /// Compares the mbool to a bool, returns true if the bool has a different value than the state of the mbool.
    5990            inline bool operator!=(bool other) const
    6091                { return this->value_.bool_ != other; }
    6192
     93            /// Compares two mbools, returns true if their memory matches.
    6294            inline bool operator==(const mbool& other) const
    6395                { return this->value_.memory_ == other.value_.memory_; }
     96            /// Compares two mbools, returns true if they have a different memory value.
    6497            inline bool operator!=(const mbool& other) const
    6598                { return this->value_.memory_ != other.value_.memory_; }
    6699
     100            /// Returns the inverted state of the bool (doesn't change the internal state).
    67101            inline bool operator!() const
    68102                { return (!this->value_.bool_); }
    69103
     104            /// Returns the memory value.
    70105            inline unsigned char& getMemory(){ return value_.memory_; }
    71106
    … …  
    73108            union
    74109            {
    75                 bool bool_ : 1;
    76                 unsigned char memory_;
    77             } value_;
     110                bool bool_ : 1;         ///< The boolean state of the mbool, is located on the first bit of the memory variable
     111                unsigned char memory_;  ///< The memory of the mbool, counts the state-changes (and the first bit represents also the boolean value)
     112            } value_;                   ///< A union containing the state and the memory of the mbool
    78113    };
    79114}
Note: See TracChangeset for help on using the changeset viewer.