Warning, file /frameworks/ktexteditor/src/include/ktexteditor/codecompletionmodelcontrollerinterface.h was not indexed or was modified since last indexation (in which case cross-reference links may be missing, inaccurate or erroneous).
0001 /* 0002 SPDX-FileCopyrightText: 2008 Niko Sams <niko.sams@gmail.com> 0003 0004 SPDX-License-Identifier: LGPL-2.0-or-later 0005 */ 0006 0007 #ifndef KTEXTEDITOR_CODECOMPLETIONMODELCONTROLLERINTERFACE_H 0008 #define KTEXTEDITOR_CODECOMPLETIONMODELCONTROLLERINTERFACE_H 0009 0010 #include "codecompletionmodel.h" 0011 #include <ktexteditor/cursor.h> 0012 #include <ktexteditor_export.h> 0013 0014 class QModelIndex; 0015 0016 namespace KTextEditor 0017 { 0018 class View; 0019 0020 /** 0021 * \class CodeCompletionModelControllerInterface codecompletionmodelcontrollerinterface.h <KTextEditor/CodeCompletionModelControllerInterface> 0022 * 0023 * \short Controller interface for a CodeCompletionModel 0024 * 0025 * \ingroup kte_group_ccmodel_extensions 0026 * 0027 * The CodeCompletionModelControllerInterface gives an CodeCompletionModel better 0028 * control over the completion. 0029 * 0030 * By implementing methods defined in this interface you can: 0031 * - control when automatic completion should start (shouldStartCompletion()) 0032 * - define a custom completion range (that will be replaced when the completion 0033 * is executed) (completionRange()) 0034 * - dynamically modify the completion range during completion (updateCompletionRange()) 0035 * - specify the string used for filtering the completion (filterString()) 0036 * - control when completion should stop (shouldAbortCompletion()) 0037 * 0038 * When the interface is not implemented, or no methods are overridden the 0039 * default behaviour is used, which will be correct in many situations. 0040 * 0041 * 0042 * \section ccmodelcontroller_impl Implementing the Interface 0043 * To use this class implement it in your CodeCompletionModel. 0044 * 0045 * \code 0046 * class MyCodeCompletion : public KTextEditor::CodeCompletionTestModel, 0047 public KTextEditor::CodeCompletionModelControllerInterface 0048 * { 0049 * Q_OBJECT 0050 * Q_INTERFACES(KTextEditor::CodeCompletionModelControllerInterface) 0051 * public: 0052 * KTextEditor::Range completionRange(KTextEditor::View* view, const KTextEditor::Cursor &position); 0053 * }; 0054 * \endcode 0055 * 0056 * \see CodeCompletionModel 0057 * \author Niko Sams \<niko.sams@gmail.com\> 0058 * \author Joseph Wenninger 0059 */ 0060 class KTEXTEDITOR_EXPORT CodeCompletionModelControllerInterface 0061 { 0062 public: 0063 CodeCompletionModelControllerInterface(); 0064 virtual ~CodeCompletionModelControllerInterface(); 0065 0066 /** 0067 * This function decides if the automatic completion should be started when 0068 * the user entered some text. 0069 * 0070 * The default implementation will return true if the last character in 0071 * \p insertedText is a letter, a number, '.', '_' or '\>' 0072 * 0073 * \param view The view to generate completions for 0074 * \param insertedText The text that was inserted by the user 0075 * \param userInsertion Whether the text was inserted by the user using typing. 0076 * If false, it may have been inserted for example by code-completion. 0077 * \param position Current cursor position 0078 * \return \e true, if the completion should be started, otherwise \e false 0079 */ 0080 virtual bool shouldStartCompletion(View *view, const QString &insertedText, bool userInsertion, const Cursor &position); 0081 0082 /** 0083 * This function returns the completion range that will be used for the 0084 * current completion. 0085 * 0086 * This range will be used for filtering the completion list and will get 0087 * replaced when executing the completion 0088 * 0089 * The default implementation will work for most languages that don't have 0090 * special chars in identifiers. Since 5.83 the default implementation takes 0091 * into account the wordCompletionRemoveTail configuration option, if that 0092 * option is enabled the whole word the cursor is inside is replaced with the 0093 * completion, however if it's disabled only the text on the left of the cursor 0094 * will be replaced with the completion. 0095 * 0096 * \param view The view to generate completions for 0097 * \param position Current cursor position 0098 * \return the completion range 0099 */ 0100 virtual Range completionRange(View *view, const Cursor &position); 0101 0102 /** 0103 * This function lets the CompletionModel dynamically modify the range. 0104 * Called after every change to the range (eg. when user entered text) 0105 * 0106 * The default implementation does nothing. 0107 * 0108 * \param view The view to generate completions for 0109 * \param range Reference to the current range 0110 * \returns the modified range 0111 */ 0112 virtual Range updateCompletionRange(View *view, const Range &range); 0113 0114 /** 0115 * This function returns the filter-text used for the current completion. 0116 * Can return an empty string to disable filtering. 0117 * 0118 * The default implementation will return the text from \p range start to 0119 * the cursor \p position. 0120 * 0121 * \param view The view to generate completions for 0122 * \param range The completion range 0123 * \param position Current cursor position 0124 * \return the string used for filtering the completion list 0125 */ 0126 virtual QString filterString(View *view, const Range &range, const Cursor &position); 0127 0128 /** 0129 * This function decides if the completion should be aborted. 0130 * Called after every change to the range (eg. when user entered text) 0131 * 0132 * The default implementation will return true when any special character was entered, or when the range is empty. 0133 * 0134 * \param view The view to generate completions for 0135 * \param range The completion range 0136 * \param currentCompletion The text typed so far 0137 * \return \e true, if the completion should be aborted, otherwise \e false 0138 */ 0139 virtual bool shouldAbortCompletion(View *view, const Range &range, const QString ¤tCompletion); 0140 0141 /** 0142 * When an item within this model is currently selected in the completion-list, and the user inserted the given character, 0143 * should the completion-item be executed? This can be used to execute items from other inputs than the return-key. 0144 * For example a function item could be executed by typing '(', or variable items by typing '.'. 0145 * \param selected The currently selected index 0146 * \param inserted The character that was inserted by tue user 0147 */ 0148 virtual bool shouldExecute(const QModelIndex &selected, QChar inserted); 0149 0150 /** 0151 * Notification that completion for this model has been aborted. 0152 * \param view The view in which the completion for this model was aborted 0153 */ 0154 virtual void aborted(View *view); 0155 0156 enum MatchReaction { 0157 None = 0, 0158 HideListIfAutomaticInvocation = 1, /** If this is returned, the completion-list is hidden if it was invoked automatically */ 0159 ForExtension = 0xffff 0160 }; 0161 0162 /** 0163 * Called whenever an item in the completion-list perfectly matches the current filter text. 0164 * \param matched The index that is matched 0165 * \return Whether the completion-list should be hidden on this event. The default-implementation always returns HideListIfAutomaticInvocation 0166 */ 0167 virtual MatchReaction matchingItem(const QModelIndex &matched); 0168 0169 /** 0170 * When multiple completion models are used at the same time, it may happen that multiple models add items with the same 0171 * name to the list. This option allows to hide items from this completion model when another model with higher priority 0172 * contains items with the same name. 0173 * \return Whether items of this completion model should be hidden if another completion model has items with the same name 0174 */ 0175 virtual bool shouldHideItemsWithEqualNames() const; 0176 }; 0177 0178 } 0179 0180 Q_DECLARE_INTERFACE(KTextEditor::CodeCompletionModelControllerInterface, "org.kde.KTextEditor.CodeCompletionModelControllerInterface") 0181 0182 #endif // KTEXTEDITOR_CODECOMPLETIONMODELCONTROLLERINTERFACE_H