KTextEditor::CodeCompletionModel Class

An item model for providing code completion, and meta information for enhanced presentation. More...

• Header: #include <KTextEditor/CodeCompletionModel>
• CMake: find_package(KF6 REQUIRED COMPONENTS TextEditor)
target_link_libraries(mytarget PRIVATE KF6::TextEditor)
• Inherits: QAbstractItemModel

List of all members, including inherited members

#Public Types

• enum CodeCompletionModel::Columns
• enum CodeCompletionModel::CompletionProperty
• enum CodeCompletionModel::ExtraItemDataRoles

#Public Functions

• CodeCompletionModel(QObject *parent)
• int columnCount(const QModelIndex &parent = QModelIndex()) const
• void completionInvoked(KTextEditor::View *view, const KTextEditor::Range &range, KTextEditor::CodeCompletionModel::InvocationType invocationType)
• void executeCompletionItem(KTextEditor::View *view, const KTextEditor::Range &word, const QModelIndex &index) const
• bool hasGroups() const
• QModelIndex index(int row, int column, const QModelIndex &parent = QModelIndex()) const
• QMap<int, QVariant> itemData(const QModelIndex &index) const
• QModelIndex parent(const QModelIndex &index) const
• int rowCount(const QModelIndex &parent = QModelIndex()) const

#Signals

• void waitForReset()

#Detailed Description

Introduction

The CodeCompletionModel is the actual workhorse to provide code completions in a KTextEditor::View. It is meant to be used in conjunction with the View. The CodeCompletionModel is not meant to be used as is. Rather you need to implement a subclass of CodeCompletionModel to actually generate completions appropriate for your type of Document.

Implementing a CodeCompletionModel

The CodeCompletionModel is a QAbstractItemModel, and can be subclassed in the same way. It provides default implementations of several members, however, so in most cases (if your completions are essentially a non-hierarchical, flat list of matches) you will only need to overload few virtual functions.

Implementing a CodeCompletionModel for a flat list

For the simple case of a flat list of completions, you will need to:

• Implement completionInvoked() to actually generate/update the list of completion matches
• implement itemData() (or QAbstractItemModel::data()) to return the information that should be displayed for each match.
• use setRowCount() to reflect the number of matches.

Columns and roles

TODO document the meaning and usage of the columns and roles used by the

Completion Interface

Using the new CodeCompletionModel

To start using your KTextEditor::View Completion Interface.

ControllerInterface to get more control

To have more control over code completion implement CodeCompletionModelControllerInterface in your CodeCompletionModel.

See also KTextEditor::CodeCompletionModelControllerInterface

#Member Type Documentation

#enum CodeCompletionModel::Columns

#enum CodeCompletionModel::CompletionProperty

flags CodeCompletionModel::CompletionProperties

The CompletionProperties type is a typedef for QFlags<CompletionProperty>. It stores an OR combination of CompletionProperty values.

#enum CodeCompletionModel::ExtraItemDataRoles

Meta information is passed through extra {Qt::ItemDataRole}s. This information should be returned when requested on the Name column.

GroupRole Using this Role, it is possible to greatly optimize the time needed to process very long completion-lists. In the completion-list, the items are usually ordered by some properties like argument-hint depth, inheritance-depth and attributes. Kate usually has to query the completion-models for these values for each item in the completion-list in order to extract the argument-hints and correctly sort the completion-list. However, with a very long completion-list, only a very small fraction of the items is actually visible. By using a tree structure you can give the items in a grouped order to kate, so it does not need to look at each item and query data in order to initially show the completion-list. This is how it works:

• You create a tree-structure for your items

• Every inner node of the tree defines one attribute value that all sub-nodes have in common.

  • When the inner node is queried for GroupRole, it should return the "ExtraItemDataRoles" that all sub-nodes have in common
  • When the inner node is then queried for that exact role, it should return that value.
  • No other queries will be done to inner nodes.

• Every leaf node stands for an actual item in the completion list.

• The recommended grouping order is: Argument-hint depth, inheritance depth, attributes. This role can also be used to define completely custom groups, bypassing the editors builtin grouping:

  • Return Qt::DisplayRole when GroupRole is requested
  • Return the label text of the group when Qt::DisplayRole
  • Optional: Return an integer sorting-value when InheritanceDepth is requested. This number will be used to determine the order of the groups. The order of the builtin groups is: 1=Best Matches, 100=Local Scope, 200=Public, 300=Protected, 400=Private, 500=Namespace, 600=Global You can pick any arbitrary number to position your group relative to these builtin groups.

UnimportantItemRole Return a nonzero value here to enforce sorting the item at the end of the list.

LastExtraItemDataRole

See also ArgumentHintDepth, ExpandingWidget

#enum CodeCompletionModel::HighlightMethod

flags CodeCompletionModel::HighlightMethods

The HighlightMethods type is a typedef for QFlags<HighlightMethod>. It stores an OR combination of HighlightMethod values.

#enum CodeCompletionModel::InvocationType

#Member Function Documentation

#[explicit] CodeCompletionModel::CodeCompletionModel(QObject *parent)

#[override virtual] int CodeCompletionModel::columnCount(const QModelIndex &parent = QModelIndex()) const

Reimplements: QAbstractItemModel::columnCount(const QModelIndex &parent) const.

Reimplemented from QAbstractItemModel::columnCount(). The default implementation returns ColumnCount for all indices.

#[virtual] void CodeCompletionModel::completionInvoked(KTextEditor::View *view, const KTextEditor::Range &range, KTextEditor::CodeCompletionModel::InvocationType invocationType)

This function is responsible to generating / updating the list of current completions. The default implementation does nothing.

When implementing this function, remember to call setRowCount() (or implement rowCount()), and to generate the appropriate change notifications (for instance by calling QAbstractItemModel::reset()).

view is the view to generate completions for

range is the range of text to generate completions for

invocationType describes how the code completion was triggered

#[virtual] void CodeCompletionModel::executeCompletionItem(KTextEditor::View *view, const KTextEditor::Range &word, const QModelIndex &index) const

This function is responsible for inserting a selected completion into the view. The default implementation replaces the text that the completions were based on with the Qt::DisplayRole of the Name column of the given match.

view is the view to insert the completion into

word is the Range that the completions are based on (what the user entered so far)

index identifies the completion match to insert

#bool CodeCompletionModel::hasGroups() const

This function returns true if the model needs grouping, otherwise false. The default is false if not changed via setHasGroups().

#[override virtual] QModelIndex CodeCompletionModel::index(int row, int column, const QModelIndex &parent = QModelIndex()) const

Reimplements: QAbstractItemModel::index(int row, int column, const QModelIndex &parent) const.

Reimplemented from QAbstractItemModel::index(). The default implementation returns a standard QModelIndex as long as the row and column are valid.

#[override virtual] QMap<int, QVariant> CodeCompletionModel::itemData(const QModelIndex &index) const

Reimplements: QAbstractItemModel::itemData(const QModelIndex &index) const.

Reimplemented from QAbstractItemModel::itemData(). The default implementation returns a map with the QAbstractItemModel::data() for all roles that are used by the CodeCompletionInterface. You will need to reimplement either this function or QAbstractItemModel::data() in your CodeCompletionModel.

#[override virtual] QModelIndex CodeCompletionModel::parent(const QModelIndex &index) const

Reimplements: QAbstractItemModel::parent(const QModelIndex &index) const.

Reimplemented from QAbstractItemModel::parent(). The default implementation returns an invalid QModelIndex for all items. This is appropriate for non-hierarchical / flat lists of completions.

#[override virtual] int CodeCompletionModel::rowCount(const QModelIndex &parent = QModelIndex()) const

Reimplements: QAbstractItemModel::rowCount(const QModelIndex &parent) const.

Reimplemented from QAbstractItemModel::rowCount(). The default implementation returns the value set by setRowCount() for invalid (toplevel) indices, and 0 for all other indices. This is appropriate for non-hierarchical / flat lists of completions

#[signal] void CodeCompletionModel::waitForReset()

Emit this if the code-completion for this model was invoked, some time is needed in order to get the data, and the model is reset once the data is available.

This only has an effect if emitted from within completionInvoked(..).

This prevents the code-completion list from showing until this model is reset, so there is no annoying flashing in the user-interface resulting from other models supplying their data earlier.

Note: The implementation may choose to show the completion-list anyway after some timeout

Warning: If you emit this, you _must_ also reset the model at some point, else the code-completion will be completely broken to the user. Consider that there may always be additional completion-models apart from yours.