File indexing completed on 2024-04-21 03:57:49

 /*
     SPDX-FileCopyrightText: 2004, 2010 Joseph Wenninger <jowenn@kde.org>
     SPDX-FileCopyrightText: 2009 Milian Wolff <mail@milianw.de>
     SPDX-FileCopyrightText: 2014 Sven Brauch <svenbrauch@gmail.com>
 
     SPDX-License-Identifier: LGPL-2.0-or-later
 */
 
 #ifndef _KATE_TEMPLATE_HANDLER_H_
 #define _KATE_TEMPLATE_HANDLER_H_
 
 #include <QList>
 #include <QObject>
 #include <QPointer>
 #include <QString>
 
 #include <katescript.h>
 #include <ktexteditor/cursor.h>
 
 class KateUndoManager;
 
 namespace KTextEditor
 {
 class DocumentPrivate;
 class ViewPrivate;
 class MovingCursor;
 class MovingRange;
 class View;
 }
 
 /**
  * \brief Inserts a template and offers advanced snippet features, like navigation and mirroring.
  *
  * For each template inserted a new KateTemplateHandler will be created.
  *
  * The handler has the following features:
  *
  * \li It inserts the template string into the document at the requested position.
  * \li When the template contains at least one variable, the cursor will be placed
  *     at the start of the first variable and its range gets selected.
  * \li When more than one variable exists,TAB and SHIFT TAB can be used to navigate
  *     to the next/previous variable.
  * \li When a variable occurs more than once in the template, edits to any of the
  *     occurrences will be mirroed to the other ones.
  * \li When ESC is pressed, the template handler closes.
  * \li When ALT + RETURN is pressed and a \c ${cursor} variable
  *     exists in the template,the cursor will be placed there. Else the cursor will
  *     be placed at the end of the template.
  *
  * \author Milian Wolff <mail@milianw.de>
  */
 
 class KateTemplateHandler : public QObject
 {
     Q_OBJECT
 
 public:
     /**
      * Setup the template handler, insert the template string.
      *
      * NOTE: The handler deletes itself when required, you do not need to
      *       keep track of it.
      */
     KateTemplateHandler(KTextEditor::ViewPrivate *view,
                         KTextEditor::Cursor position,
                         const QString &templateString,
                         const QString &script,
                         KateUndoManager *undoManager);
 
     ~KateTemplateHandler() override;
 
 protected:
     /**
      * \brief Provide keyboard interaction for the template handler.
      *
      * The event filter handles the following shortcuts:
      *
      * TAB: jump to next editable (i.e. not mirrored) range.
      *      NOTE: this prevents indenting via TAB.
      * SHIFT + TAB: jump to previous editable (i.e. not mirrored) range.
      *      NOTE: this prevents un-indenting via SHIFT + TAB.
      * ESC: terminate template handler (only when no completion is active).
      * ALT + RETURN: accept template and jump to the end-cursor.
      *               if %{cursor} was given in the template, that will be the
      *               end-cursor.
      *               else just jump to the end of the inserted text.
      */
     bool eventFilter(QObject *object, QEvent *event) override;
 
 private:
     /**
      * Inserts the @p text template at @p position and performs
      * all necessary initializations, such as populating default values
      * and placing the cursor.
      */
     void initializeTemplate();
 
     /**
      * Parse @p templateText and populate m_fields.
      */
     void parseFields(const QString &templateText);
 
     /**
      * Set necessary attributes (esp. background colour) on all moving
      * ranges for the fields in m_fields.
      */
     void setupFieldRanges();
 
     /**
      * Evaluate default values for all fields in m_fields and
      * store them in the fields. This updates the @property defaultValue property
      * of the TemplateField instances in m_fields from the raw, user-entered
      * default value to its evaluated equivalent (e.g. "func()" -> result of function call)
      *
      * @sa TemplateField
      */
     void setupDefaultValues();
 
     /**
      * Install an event filter on the filter proxy of \p view for
      * navigation between the ranges and terminating the KateTemplateHandler.
      *
      * \see eventFilter()
      */
     void setupEventHandler(KTextEditor::View *view);
 
     /**
      * Jumps to the previous editable range. If there is none, wrap and jump to the first range.
      *
      * \see jumpToNextRange()
      */
     void jumpToPreviousRange();
 
     /**
      * Jumps to the next editable range. If there is none, wrap and jump to the last range.
      *
      * \see jumpToPreviousRange()
      */
     void jumpToNextRange();
 
     /**
      * Helper function for jumpTo{Next,Previous}
      * if initial is set to true, assumes the cursor is before the snippet
      * and selects the first field
      */
     void jump(int by, bool initial = false);
 
     /**
      * Jumps to the final cursor position. This is either \p m_finalCursorPosition, or
      * if that is not set, the end of \p m_templateRange.
      */
     void jumpToFinalCursorPosition();
 
     /**
      * Go through all template fields and decide if their moving ranges expand
      * when edited at the corners. Expansion is turned off if two fields are
      * directly adjacent to avoid overlaps when characters are inserted between
      * them.
      */
     void updateRangeBehaviours();
 
     /**
      * Sort all template fields in m_fields by tab order, which means,
      * by range; except for ${cursor} which is always sorted last.
      */
     void sortFields();
 
 private Q_SLOTS:
     /**
      * Saves the range of the inserted template. This is required since
      * tabs could get expanded on insert. While we are at it, we can
      * use it to auto-indent the code after insert.
      */
     void slotTemplateInserted(KTextEditor::Document *document, KTextEditor::Range range);
 
     /**
      * Install event filter on new views.
      */
     void slotViewCreated(KTextEditor::Document *document, KTextEditor::View *view);
 
     /**
      * Update content of all dependent fields, i.e. mirror or script fields.
      */
     void updateDependentFields(KTextEditor::Document *document, KTextEditor::Range oldRange);
 
 public:
     KTextEditor::ViewPrivate *view() const;
     KTextEditor::DocumentPrivate *doc() const;
 
 private:
     /// The view we operate on
     KTextEditor::ViewPrivate *m_view;
     /// The undo manager associated with our document
     KateUndoManager *const m_undoManager;
 
     // Describes a single template field, e.g. ${foo}.
     struct TemplateField {
         // up-to-date range for the field
         std::shared_ptr<KTextEditor::MovingRange> range;
         // contents of the field, i.e. identifier or function to call
         QString identifier;
         // default value, if applicable; else empty
         QString defaultValue;
         enum Kind {
             Invalid, // not an actual field
             Editable, // normal, user-editable field (green by default) [non-dependent field]
             Mirror, // field mirroring contents of another field [dependent field]
             FunctionCall, // field containing the up-to-date result of a function call [dependent field]
             FinalCursorPosition // field marking the final cursor position
         };
         Kind kind = Invalid;
         // true if this field was edited by the user before
         bool touched = false;
         bool operator==(const TemplateField &other) const
         {
             return range == other.range;
         }
     };
     // List of all template fields in the inserted snippet. @see sortFields()
     QList<TemplateField> m_fields;
 
     // Get the template field which contains @p range.
     const TemplateField fieldForRange(KTextEditor::Range range) const;
 
     /// Construct a map of master fields and their current value, for use in scripts.
     KateScript::FieldMap fieldMap() const;
 
     /// A range that occupies the whole range of the inserted template.
     /// When the an edit happens outside it, the template handler gets closed.
     std::shared_ptr<KTextEditor::MovingRange> m_wholeTemplateRange;
 
     /// Set to true when currently updating dependent fields, to prevent recursion.
     bool m_internalEdit;
 
     /// template script (i.e. javascript stuff), which can be used by the current template
     KateScript m_templateScript;
 };
 
 #endif