From 838fabab104f1ccf0210746c0334ba13e921241a Mon Sep 17 00:00:00 2001 From: bruneton Date: Thu, 4 Apr 2013 14:39:24 +0000 Subject: [PATCH] PyConsole/PyInterp: documentation. --- src/PyConsole/PyConsole_Editor.cxx | 5 +++- src/PyConsole/PyConsole_EnhEditor.cxx | 43 ++++++++++++++++++++++++++- src/PyConsole/PyConsole_EnhEditor.h | 2 +- src/PyConsole/PyConsole_EnhInterp.h | 2 +- src/PyConsole/PyConsole_Request.cxx | 33 +++++++++++++++++++- src/PyConsole/PyConsole_Request.h | 12 ++------ src/PyInterp/PyInterp_Event.h | 5 +++- 7 files changed, 87 insertions(+), 15 deletions(-) diff --git a/src/PyConsole/PyConsole_Editor.cxx b/src/PyConsole/PyConsole_Editor.cxx index 049eabb42..aac8a4d4b 100644 --- a/src/PyConsole/PyConsole_Editor.cxx +++ b/src/PyConsole/PyConsole_Editor.cxx @@ -116,6 +116,7 @@ #include #include #include +#include static QString READY_PROMPT = ">>> "; static QString DOTS_PROMPT = "... "; @@ -544,7 +545,9 @@ void PyConsole_Editor::keyPressEvent( QKeyEvent* event ) } // check for printed key - aKey = ( aKey < Qt::Key_Space || aKey > Qt::Key_ydiaeresis ) ? aKey : 0; + // #### aKey = ( aKey < Qt::Key_Space || aKey > Qt::Key_ydiaeresis ) ? aKey : 0; + // Better: + aKey = !(QChar(aKey).isPrint()) ? aKey : 0; switch ( aKey ) { case 0 : diff --git a/src/PyConsole/PyConsole_EnhEditor.cxx b/src/PyConsole/PyConsole_EnhEditor.cxx index aa73d152f..aaec2b1d8 100644 --- a/src/PyConsole/PyConsole_EnhEditor.cxx +++ b/src/PyConsole/PyConsole_EnhEditor.cxx @@ -38,6 +38,11 @@ static const char * tmp_a[] = {" ", "(", "[","+", "-", "*", "/", ";", "^", "="}; const std::vector PyConsole_EnhEditor::SEPARATORS = \ std::vector(tmp_a, tmp_a + sizeof(tmp_a)/sizeof(tmp_a[0])); +/** + * Constructor. + * @param interp the interpreter linked to the editor + * @param parent parent widget + */ PyConsole_EnhEditor::PyConsole_EnhEditor(PyConsole_EnhInterp * interp, QWidget * parent) : PyConsole_Editor(interp, parent), _tab_mode(false), @@ -46,6 +51,10 @@ PyConsole_EnhEditor::PyConsole_EnhEditor(PyConsole_EnhInterp * interp, QWidget * document()->setUndoRedoEnabled(true); } +/** + * Overrides. Catches the TAB and Ctrl+TAB combinations. + * @param event + */ void PyConsole_EnhEditor::keyPressEvent ( QKeyEvent* event) { // check if is pressed @@ -66,7 +75,9 @@ void PyConsole_EnhEditor::keyPressEvent ( QKeyEvent* event) } else { - if (!ctrlPressed) + // If ctrl is not pressed (and sth else is pressed with it), + // or if ctrl is not pressed alone + if (!ctrlPressed || (ctrlPressed && event->key() != Qt::Key_Control)) { clearCompletion(); _cursor_pos = -1; @@ -75,6 +86,10 @@ void PyConsole_EnhEditor::keyPressEvent ( QKeyEvent* event) } } +/** + * Whenever the mouse is clicked, clear the completion. + * @param e + */ void PyConsole_EnhEditor::mousePressEvent(QMouseEvent* e) { clearCompletion(); @@ -82,6 +97,9 @@ void PyConsole_EnhEditor::mousePressEvent(QMouseEvent* e) PyConsole_Editor::mousePressEvent(e); } +/** + * Clear in the editor the block of text displayed after having hit . + */ void PyConsole_EnhEditor::clearCompletion() { // Delete completion text if present @@ -100,6 +118,9 @@ void PyConsole_EnhEditor::clearCompletion() _tab_mode = false; } +/** + * Handle the sequence of events after having hit + */ void PyConsole_EnhEditor::handleTab() { if (_tab_mode) @@ -133,6 +154,9 @@ void PyConsole_EnhEditor::handleTab() PyInterp_Dispatcher::Get()->Exec(req); } +/** + * Handles what happens after hitting Ctrl-TAB + */ void PyConsole_EnhEditor::handleBackTab() { QTextCursor cursor(textCursor()); @@ -154,6 +178,13 @@ void PyConsole_EnhEditor::handleBackTab() _cursor_pos = -1; } +/** + * Create the Python requested that will be posted to the interpreter to + * get the completions. + * @param input line typed by the user at the time TAB was hit + * @return a CompletionCommand + * @sa CompletionCommand + */ PyInterp_Request* PyConsole_EnhEditor::createTabRequest( const QString& input ) { // Parse input to extract on what part the dir() has to be executed @@ -213,6 +244,11 @@ void PyConsole_EnhEditor::formatCompletion(const std::vector & matches, } } +/** + * Override. Catches the events generated by the enhanced interpreter after the execution + * of a completion request. + * @param event + */ void PyConsole_EnhEditor::customEvent( QEvent* event ) { std::vector matches; @@ -317,6 +353,11 @@ void PyConsole_EnhEditor::extractCommon(const std::vector & matches, QS } } +/** + * Format the doc string in HTML format with the first line in bold blue + * @param doc initial doc string + * @return HTML string + */ QString PyConsole_EnhEditor::formatDocHTML(const QString & doc) const { QString templ = QString(" +/** + * Constructor. + * @param theInterp interpreter that will execute the command + * @param theCommand command text + * @param theListener editor object that will receive the response events after execution + * of the request + * @param sync + */ ExecCommand::ExecCommand( PyInterp_Interp* theInterp, const QString& theCommand, PyConsole_Editor* theListener, @@ -36,6 +44,9 @@ ExecCommand::ExecCommand( PyInterp_Interp* theInterp, myCommand( theCommand ), myState( PyInterp_Event::ES_OK ) {} +/** + * Execute the command by calling the run() method of the embedded interpreter. + */ void ExecCommand::execute() { if ( myCommand != "" ) @@ -48,6 +59,10 @@ void ExecCommand::execute() } } +/** + * Create the event indicating the status of the request execution. + * @return a QEvent + */ QEvent* ExecCommand::createEvent() { if ( IsSync() ) @@ -56,7 +71,15 @@ QEvent* ExecCommand::createEvent() } - +/*! + Constructor. + Creates a new python completion request. + \param theInterp python interpreter + \param input string containing the dir() command to be executed + \param startMatch part to be matched with the results of the dir() command + \param theListener widget to get the notification messages + \param sync if True the request is processed synchronously +*/ CompletionCommand::CompletionCommand( PyConsole_EnhInterp* theInterp, const QString& input, const QString& startMatch, @@ -66,6 +89,10 @@ CompletionCommand::CompletionCommand( PyConsole_EnhInterp* theInterp, _tabSuccess(false), _dirArg(input), _startMatch(startMatch) {} +/** + * Execute the completion command by wrapping the runDirCommand() of the + * embedded enhanced interpreter. + */ void CompletionCommand::execute() { PyConsole_EnhInterp * interp = static_cast(getInterp()); @@ -76,6 +103,10 @@ void CompletionCommand::execute() _tabSuccess = false; } +/** + * Create the event indicating the return value of the completion command. + * @return + */ QEvent* CompletionCommand::createEvent() { int typ = _tabSuccess ? PyInterp_Event::ES_TAB_COMPLETE_OK : PyInterp_Event::ES_TAB_COMPLETE_ERR; diff --git a/src/PyConsole/PyConsole_Request.h b/src/PyConsole/PyConsole_Request.h index d20bcd84a..ccfea0c55 100644 --- a/src/PyConsole/PyConsole_Request.h +++ b/src/PyConsole/PyConsole_Request.h @@ -79,15 +79,6 @@ class PyConsole_EnhEditor; class CompletionCommand : public PyInterp_LockRequest { public: - /*! - Constructor. - Creates a new python completion request. - \param theInterp python interpreter - \param input string containing the dir() command to be executed - \param startMatch part to be matched with the results of the dir() command - \param theListener widget to get the notification messages - \param sync if True the request is processed synchronously - */ CompletionCommand( PyConsole_EnhInterp* theInterp, const QString& input, const QString& startMatch, @@ -99,8 +90,11 @@ protected: /** List of separators identifying the last parsable token for completion */ static const std::vector SEPARATORS; + /** String to be passed to the dir() command */ QString _dirArg; + /** Begining of the command (as typed by the user) */ QString _startMatch; + /** was the completion command successful */ bool _tabSuccess; virtual void execute(); diff --git a/src/PyInterp/PyInterp_Event.h b/src/PyInterp/PyInterp_Event.h index 44e40ba9c..3a1640054 100644 --- a/src/PyInterp/PyInterp_Event.h +++ b/src/PyInterp/PyInterp_Event.h @@ -47,7 +47,10 @@ protected: PyInterp_Request* myRequest; }; - +/** + * Events thrown by the interpreter having executed a command and indicating + * the return status. + */ class PYINTERP_EXPORT PyInterp_Event : public QEvent { PyInterp_Event(); -- 2.39.2