Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Ignore:
Timestamp:
Sep 4, 2010, 11:33:02 PM (15 years ago)
Author:
landauf
Message:

added documentation

also some small naming and readability changes in the code.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • code/branches/doc/src/libraries/core/command/ConsoleCommand.h

    r7284 r7352  
    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); }
Note: See TracChangeset for help on using the changeset viewer.