Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Changeset 7361


Ignore:
Timestamp:
Sep 5, 2010, 10:51:55 PM (10 years ago)
Author:
landauf
Message:

added documentation

Location:
code/branches/doc
Files:
15 edited

Legend:

Unmodified
Added
Removed
  • code/branches/doc/doc/api/Groups.dox

    r7357 r7361  
    5959
    6060/**
    61     @defgroup CmdArgs Commandline Arguments
    62     @ingroup Command
    63     @brief For a reference see @ref cmdargspage
    64 */
    65 
    66 /**
    6761    @defgroup Config Config
    6862    @ingroup Core
     
    7670/**
    7771    @defgroup Input Input
    78     @ingroup Core
    79 */
    80 
    81 /**
    82     @defgroup Output Output
    8372    @ingroup Core
    8473*/
  • code/branches/doc/src/libraries/core/CommandLineParser.h

    r7357 r7361  
    2626 *
    2727 */
     28
     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*/
    2839
    2940#ifndef _CommandLine_H__
  • code/branches/doc/src/libraries/core/command/IOConsole.h

    r7287 r7361  
    2727 */
    2828
     29/**
     30    @file
     31    @ingroup Command ShellConsole
     32*/
     33
    2934#include "OrxonoxConfig.h"
    3035
  • code/branches/doc/src/libraries/core/command/IOConsolePOSIX.h

    r7287 r7361  
    2727 *
    2828 */
     29
     30/**
     31    @file
     32    @ingroup Command ShellConsole
     33*/
    2934
    3035#ifndef _IOConsole_H__
  • code/branches/doc/src/libraries/core/command/IOConsoleWindows.h

    r7287 r7361  
    2626 *
    2727 */
     28
     29/**
     30    @file
     31    @ingroup Command ShellConsole
     32*/
    2833
    2934#ifndef _IOConsole_H__
  • code/branches/doc/src/libraries/core/command/IRC.cc

    r7284 r7361  
    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/branches/doc/src/libraries/core/command/IRC.h

    r7284 r7361  
    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/branches/doc/src/libraries/core/command/Shell.cc

    r7284 r7361  
    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/branches/doc/src/libraries/core/command/Shell.h

    r7284 r7361  
    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/branches/doc/src/libraries/core/command/TclBind.cc

    r7284 r7361  
    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/branches/doc/src/libraries/core/command/TclBind.h

    r7284 r7361  
    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/branches/doc/src/libraries/core/command/TclThreadList.h

    r7297 r7361  
    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
  • code/branches/doc/src/libraries/core/command/TclThreadManager.cc

    r7297 r7361  
    2626 *
    2727 */
     28
     29/**
     30    @file
     31    @brief Implementation of TclThreadManager.
     32*/
    2833
    2934#include "TclThreadManager.h"
     
    387392        @param target_id The id of the target thread
    388393        @param command The command to send as a query
    389         @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().
    390395    */
    391396    std::string TclThreadManager::_query(unsigned int source_id, unsigned int target_id, const std::string& command, bool bUseCommandExecutor)
  • code/branches/doc/src/libraries/core/command/TclThreadManager.h

    r7284 r7361  
    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/branches/doc/src/libraries/util/Debug.h

    r7352 r7361  
    3030/**
    3131    @defgroup COUT COUT(x) output macro
    32     @ingroup Util Output
     32    @ingroup Util
    3333*/
    3434
Note: See TracChangeset for help on using the changeset viewer.