qgscodeeditor.h

Go to the documentation of this file.

/***************************************************************************
    qgscodeeditor.h - A base code editor for QGIS and plugins.  Provides
                      a base editor using QScintilla for editors
     --------------------------------------
    Date                 : 06-Oct-2013
    Copyright            : (C) 2013 by Salvatore Larosa
    Email                : lrssvtml (at) gmail (dot) com
 ***************************************************************************
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 ***************************************************************************/
 
#ifndef QGSCODEEDITOR_H
#define QGSCODEEDITOR_H
 
#include "qgis.h"
#include "qgscodeeditorcolorscheme.h"
#include "qgspanelwidget.h"
#include "qgssettingstree.h"
 
#include <QString>
 
using namespace Qt::StringLiterals;
 
// qscintilla includes
#include <Qsci/qsciapis.h>
#include "qgis_sip.h"
#include "qgis_gui.h"
 
#include <QMap>
 
class QgsFilterLineEdit;
class QToolButton;
class QCheckBox;
class QgsSettingsEntryBool;
 
SIP_IF_MODULE( HAVE_QSCI_SIP )
 

class GUI_EXPORT QgsCodeInterpreter
{
  public:
    virtual ~QgsCodeInterpreter();

    int exec( const QString &command );

    virtual int currentState() const { return mState; }

    virtual QString promptForState( int state ) const = 0;
 
  protected:
    virtual int execCommandImpl( const QString &command ) = 0;
 
  private:
    int mState = 0;
};
 
 
// TODO QGIS 5.0 -- Consider making QgsCodeEditor inherit QWidget only,
// with a separate getter for the QsciScintilla child widget. This
// would give us more flexibility to add functionality to the base
// QgsCodeEditor class, eg adding a message bar or other child widgets
// to the editor widget. For now this extra functionality lives in
// the QgsCodeEditorWidget wrapper widget.

class GUI_EXPORT QgsCodeEditor : public QsciScintilla
{
    Q_OBJECT
 
  public:
#ifndef SIP_RUN
 
    static inline QgsSettingsTreeNode *sTreeCodeEditor = QgsSettingsTree::sTreeGui->createChildNode( u"code-editor"_s );
    static const QgsSettingsEntryBool *settingContextHelpHover;
#endif

    enum class Mode
    {
      ScriptEditor,  
      OutputDisplay, 
      CommandInput,  
    };
    Q_ENUM( Mode )
 
    
    enum class MarginRole SIP_MONKEYPATCH_SCOPEENUM_UNNEST( QgsCodeEditor, MarginRole ) : int
    {
      LineNumbers = 0,     
      ErrorIndicators = 1, 
      FoldingControls = 2, 
    };
    Q_ENUM( MarginRole )
 
    
    enum class Flag : int SIP_ENUM_BASETYPE( IntFlag )
    {
      CodeFolding = 1 << 0, 
      ImmediatelyUpdateHistory
      = 1 << 1, 
    };
    Q_ENUM( Flag )
 
    
    Q_DECLARE_FLAGS( Flags, Flag )
    Q_FLAG( Flags )

    static constexpr int SEARCH_RESULT_INDICATOR = QsciScintilla::INDIC_MAX - 1;

    QgsCodeEditor(
      QWidget *parent SIP_TRANSFERTHIS = nullptr,
      const QString &title = QString(),
      bool folding = false,
      bool margin = false,
      QgsCodeEditor::Flags flags = QgsCodeEditor::Flags(),
      QgsCodeEditor::Mode mode = QgsCodeEditor::Mode::ScriptEditor
    );

    void setTitle( const QString &title );

    virtual Qgis::ScriptLanguage language() const;

    virtual Qgis::ScriptLanguageCapabilities languageCapabilities() const;

    static QString languageToString( Qgis::ScriptLanguage language );

    Q_DECL_DEPRECATED void setMarginVisible( bool margin ) SIP_DEPRECATED;

    Q_DECL_DEPRECATED bool marginVisible() SIP_DEPRECATED { return mMargin; }

    void setLineNumbersVisible( bool visible );

    bool lineNumbersVisible() const;

    void setFoldingVisible( bool folding );

    bool foldingVisible();

    void insertText( const QString &text );

    static QColor defaultColor( QgsCodeEditorColorScheme::ColorRole role, const QString &theme = QString() );

    static QColor color( QgsCodeEditorColorScheme::ColorRole role );

    static void setColor( QgsCodeEditorColorScheme::ColorRole role, const QColor &color );

    static QFont getMonospaceFont();

    void setCustomAppearance(
      const QString &scheme = QString(),
      const QMap<QgsCodeEditorColorScheme::ColorRole, QColor> &customColors = QMap<QgsCodeEditorColorScheme::ColorRole, QColor>(),
      const QString &fontFamily = QString(),
      int fontSize = 0
    ) SIP_SKIP;

    void addWarning( int lineNumber, const QString &warning );

    void clearWarnings();

    QgsCodeEditor::Mode mode() const { return mMode; }

    bool isCursorOnLastLine() const;

    void setHistoryFilePath( const QString &path );

    QStringList history() const;

    QgsCodeInterpreter *interpreter() const;

    void setInterpreter( QgsCodeInterpreter *newInterpreter );

    int linearPosition() const;

    void setLinearPosition( int position );

    int selectionStart() const;

    int selectionEnd() const;

    void setLinearSelection( int start, int end );
 
    // Override QsciScintilla::callTip to handle wrapping
    void callTip() override;

    int wrapPosition( int line = -1 );
 

    int editingTimeoutInterval() const;
 
 
  public slots:

    void runCommand( const QString &command, bool skipHistory = false );

    virtual void moveCursorToStart();

    virtual void moveCursorToEnd();

    void showPreviousCommand();

    void showNextCommand();

    void showHistory();

    void removeHistoryCommand( int index );

    void clearSessionHistory();

    void clearPersistentHistory();

    bool writeHistoryFile();

    void reformatCode();

    virtual bool checkSyntax();

    virtual void toggleComment();

    void adjustScrollWidth();
 
    // Override QsciScintilla::setText to adjust the scroll width
    void setText( const QString &text ) override;

    void setEditingTimeoutInterval( int timeout );
 
  signals:

    void sessionHistoryCleared();

    void persistentHistoryCleared();
 

    void helpRequested( const QString &word );
 

    void editingTimeout();
 
  protected:
    static bool isFixedPitch( const QFont &font );
 
    void focusOutEvent( QFocusEvent *event ) override;
    void keyPressEvent( QKeyEvent *event ) override;
    void contextMenuEvent( QContextMenuEvent *event ) override;
    bool event( QEvent *event ) override;
    bool eventFilter( QObject *watched, QEvent *event ) override;

    virtual void initializeLexer();

    QColor lexerColor( QgsCodeEditorColorScheme::ColorRole role ) const;

    QFont lexerFont() const;

    void runPostLexerConfigurationTasks();

    void updateSoftHistory();

    void updatePrompt();

    virtual void populateContextMenu( QMenu *menu );

    virtual QString reformatCodeString( const QString &string );

    virtual void showMessage( const QString &title, const QString &message, Qgis::MessageLevel level );

    void toggleLineComments( const QString &commentPrefix );
 
  private slots:
    void onLastEditTimeout();
 
  private:
    void setSciWidget();
    void updateFolding();
    bool readHistoryFile();
    void syncSoftHistory();
    void updateHistory( const QStringList &commands, bool skipSoftHistory = false );
    char getCharacter( int &pos ) const;
 
    QString mWidgetTitle;
    bool mMargin = false;
    QgsCodeEditor::Flags mFlags;
    QgsCodeEditor::Mode mMode = QgsCodeEditor::Mode::ScriptEditor;
 
    bool mUseDefaultSettings = true;
    // used if above is false, inplace of values taken from QSettings:
    bool mOverrideColors = false;
    QString mColorScheme;
    QMap<QgsCodeEditorColorScheme::ColorRole, QColor> mCustomColors;
    QString mFontFamily;
    int mFontSize = 0;
 
    QVector<int> mWarningLines;
 
    // for use in command input mode
    QStringList mHistory;
    QStringList mSoftHistory;
    int mSoftHistoryIndex = 0;
    QString mHistoryFilePath;
 
    QgsCodeInterpreter *mInterpreter = nullptr;
 
    static QMap<QgsCodeEditorColorScheme::ColorRole, QString> sColorRoleToSettingsKey;
 
    static constexpr int MARKER_NUMBER = 6;
 
    QTimer *mLastEditTimer = nullptr;
};
 
Q_DECLARE_OPERATORS_FOR_FLAGS( QgsCodeEditor::Flags )
 
// clazy:excludeall=qstring-allocations
 
#endif