1 /* 2 SPDX-FileCopyrightText: 2008 Niko Sams <niko.sams@gmail.com> 3 4 SPDX-License-Identifier: LGPL-2.0-or-later 5 */ 6 7 #ifndef KTEXTEDITOR_CODECOMPLETIONMODELCONTROLLERINTERFACE_H 8 #define KTEXTEDITOR_CODECOMPLETIONMODELCONTROLLERINTERFACE_H 9 10 #include "codecompletionmodel.h" 11 #include <ktexteditor/cursor.h> 12 #include <ktexteditor_export.h> 13 14 class QModelIndex; 15 16 namespace KTextEditor 17 { 18 class View; 19 20 /** 21 * \class CodeCompletionModelControllerInterface codecompletionmodelcontrollerinterface.h <KTextEditor/CodeCompletionModelControllerInterface> 22 * 23 * \short Controller interface for a CodeCompletionModel 24 * 25 * \ingroup kte_group_ccmodel_extensions 26 * 27 * The CodeCompletionModelControllerInterface gives an CodeCompletionModel better 28 * control over the completion. 29 * 30 * By implementing methods defined in this interface you can: 31 * - control when automatic completion should start (shouldStartCompletion()) 32 * - define a custom completion range (that will be replaced when the completion 33 * is executed) (completionRange()) 34 * - dynamically modify the completion range during completion (updateCompletionRange()) 35 * - specify the string used for filtering the completion (filterString()) 36 * - control when completion should stop (shouldAbortCompletion()) 37 * 38 * When the interface is not implemented, or no methods are overridden the 39 * default behaviour is used, which will be correct in many situations. 40 * 41 * 42 * \section ccmodelcontroller_impl Implementing the Interface 43 * To use this class implement it in your CodeCompletionModel. 44 * 45 * \code 46 * class MyCodeCompletion : public KTextEditor::CodeCompletionTestModel, 47 public KTextEditor::CodeCompletionModelControllerInterface 48 * { 49 * Q_OBJECT 50 * Q_INTERFACES(KTextEditor::CodeCompletionModelControllerInterface) 51 * public: 52 * KTextEditor::Range completionRange(KTextEditor::View* view, const KTextEditor::Cursor &position); 53 * }; 54 * \endcode 55 * 56 * \see CodeCompletionModel 57 * \author Niko Sams \<niko.sams@gmail.com\> 58 * \author Joseph Wenninger 59 */ 60 class KTEXTEDITOR_EXPORT CodeCompletionModelControllerInterface 61 { 62 public: 63 CodeCompletionModelControllerInterface(); 64 virtual ~CodeCompletionModelControllerInterface(); 65 66 /** 67 * This function decides if the automatic completion should be started when 68 * the user entered some text. 69 * 70 * The default implementation will return true if the last character in 71 * \p insertedText is a letter, a number, '.', '_' or '\>' 72 * 73 * \param view The view to generate completions for 74 * \param insertedText The text that was inserted by the user 75 * \param userInsertion Whether the text was inserted by the user using typing. 76 * If false, it may have been inserted for example by code-completion. 77 * \param position Current cursor position 78 * \return \e true, if the completion should be started, otherwise \e false 79 */ 80 virtual bool shouldStartCompletion(View *view, const QString &insertedText, bool userInsertion, const Cursor &position); 81 82 /** 83 * This function returns the completion range that will be used for the 84 * current completion. 85 * 86 * This range will be used for filtering the completion list and will get 87 * replaced when executing the completion 88 * 89 * The default implementation will work for most languages that don't have 90 * special chars in identifiers. Since 5.83 the default implementation takes 91 * into account the wordCompletionRemoveTail configuration option, if that 92 * option is enabled the whole word the cursor is inside is replaced with the 93 * completion, however if it's disabled only the text on the left of the cursor 94 * will be replaced with the completion. 95 * 96 * \param view The view to generate completions for 97 * \param position Current cursor position 98 * \return the completion range 99 */ 100 virtual Range completionRange(View *view, const Cursor &position); 101 102 /** 103 * This function lets the CompletionModel dynamically modify the range. 104 * Called after every change to the range (eg. when user entered text) 105 * 106 * The default implementation does nothing. 107 * 108 * \param view The view to generate completions for 109 * \param range Reference to the current range 110 * \returns the modified range 111 */ 112 virtual Range updateCompletionRange(View *view, const Range &range); 113 114 /** 115 * This function returns the filter-text used for the current completion. 116 * Can return an empty string to disable filtering. 117 * 118 * The default implementation will return the text from \p range start to 119 * the cursor \p position. 120 * 121 * \param view The view to generate completions for 122 * \param range The completion range 123 * \param position Current cursor position 124 * \return the string used for filtering the completion list 125 */ 126 virtual QString filterString(View *view, const Range &range, const Cursor &position); 127 128 /** 129 * This function decides if the completion should be aborted. 130 * Called after every change to the range (eg. when user entered text) 131 * 132 * The default implementation will return true when any special character was entered, or when the range is empty. 133 * 134 * \param view The view to generate completions for 135 * \param range The completion range 136 * \param currentCompletion The text typed so far 137 * \return \e true, if the completion should be aborted, otherwise \e false 138 */ 139 virtual bool shouldAbortCompletion(View *view, const Range &range, const QString ¤tCompletion); 140 141 /** 142 * When an item within this model is currently selected in the completion-list, and the user inserted the given character, 143 * should the completion-item be executed? This can be used to execute items from other inputs than the return-key. 144 * For example a function item could be executed by typing '(', or variable items by typing '.'. 145 * \param selected The currently selected index 146 * \param inserted The character that was inserted by tue user 147 */ 148 virtual bool shouldExecute(const QModelIndex &selected, QChar inserted); 149 150 /** 151 * Notification that completion for this model has been aborted. 152 * \param view The view in which the completion for this model was aborted 153 */ 154 virtual void aborted(View *view); 155 156 enum MatchReaction { 157 None = 0, 158 HideListIfAutomaticInvocation = 1, /** If this is returned, the completion-list is hidden if it was invoked automatically */ 159 ForExtension = 0xffff 160 }; 161 162 /** 163 * Called whenever an item in the completion-list perfectly matches the current filter text. 164 * \param matched The index that is matched 165 * \return Whether the completion-list should be hidden on this event. The default-implementation always returns HideListIfAutomaticInvocation 166 */ 167 virtual MatchReaction matchingItem(const QModelIndex &matched); 168 169 /** 170 * When multiple completion models are used at the same time, it may happen that multiple models add items with the same 171 * name to the list. This option allows to hide items from this completion model when another model with higher priority 172 * contains items with the same name. 173 * \return Whether items of this completion model should be hidden if another completion model has items with the same name 174 */ 175 virtual bool shouldHideItemsWithEqualNames() const; 176 }; 177 178 } 179 180 Q_DECLARE_INTERFACE(KTextEditor::CodeCompletionModelControllerInterface, "org.kde.KTextEditor.CodeCompletionModelControllerInterface") 181 182 #endif // KTEXTEDITOR_CODECOMPLETIONMODELCONTROLLERINTERFACE_H 183