QCompleter¶

The QCompleter class provides completions based on an item model. More…

Synopsis¶

Functions¶

def caseSensitivity ()
def completionColumn ()
def completionCount ()
def completionMode ()
def completionModel ()
def completionPrefix ()
def completionRole ()
def currentCompletion ()
def currentIndex ()
def currentRow ()
def filterMode ()
def maxVisibleItems ()
def model ()
def modelSorting ()
def popup ()
def setCaseSensitivity (caseSensitivity)
def setCompletionColumn (column)
def setCompletionMode (mode)
def setCompletionRole (role)
def setCurrentRow (row)
def setFilterMode (filterMode)
def setMaxVisibleItems (maxItems)
def setModel (c)
def setModelSorting (sorting)
def setPopup (popup)
def setWidget (widget)
def widget ()
def wrapAround ()

Virtual functions¶

def pathFromIndex (index)
def splitPath (path)

Slots¶

def complete ([rect=QRect()])
def setCompletionPrefix (prefix)
def setWrapAround (wrap)

Signals¶

def activated (index)
def activated (text)
def highlighted (index)
def highlighted (text)

Detailed Description¶

You can use QCompleter to provide auto completions in any Qt widget, such as QLineEdit and QComboBox . When the user starts typing a word, QCompleter suggests possible ways of completing the word, based on a word list. The word list is provided as a QAbstractItemModel . (For simple applications, where the word list is static, you can pass a QStringList to QCompleter ‘s constructor.)

Basic Usage¶

A QCompleter is used typically with a QLineEdit or QComboBox . For example, here’s how to provide auto completions from a simple word list in a QLineEdit :

wordList = QStringList()
wordList << "alpha" << "omega" << "omicron" << "zeta"
lineEdit = QLineEdit(self)
completer = QCompleter(wordList, self)
completer.setCaseSensitivity(Qt.CaseInsensitive)
lineEdit.setCompleter(completer)

A QFileSystemModel can be used to provide auto completion of file names. For example:

completer = QCompleter(self)
completer.setModel(QFileSystemModel(completer))
lineEdit.setCompleter(completer)

To set the model on which QCompleter should operate, call setModel() . By default, QCompleter will attempt to match the completion prefix (i.e., the word that the user has started typing) against the EditRole data stored in column 0 in the model case sensitively. This can be changed using setCompletionRole() , setCompletionColumn() , and setCaseSensitivity() .

If the model is sorted on the column and role that are used for completion, you can call setModelSorting() with either CaseSensitivelySortedModel or CaseInsensitivelySortedModel as the argument. On large models, this can lead to significant performance improvements, because QCompleter can then use binary search instead of linear search. The binary search only works when the filterMode is MatchStartsWith .

The model can be a list model , a table model , or a tree model . Completion on tree models is slightly more involved and is covered in the Handling Tree Models section below.

The completionMode() determines the mode used to provide completions to the user.

Iterating Through Completions¶

To retrieve a single candidate string, call setCompletionPrefix() with the text that needs to be completed and call currentCompletion() . You can iterate through the list of completions as below:

for (int i = 0; completer.setCurrentRow(i); i++)
    print(completer.currentCompletion(), " is match number ", i)

completionCount() returns the total number of completions for the current prefix. completionCount() should be avoided when possible, since it requires a scan of the entire model.

The Completion Model¶

completionModel() return a list model that contains all possible completions for the current completion prefix, in the order in which they appear in the model. This model can be used to display the current completions in a custom view. Calling setCompletionPrefix() automatically refreshes the completion model.

Handling Tree Models¶

QCompleter can look for completions in tree models, assuming that any item (or sub-item or sub-sub-item) can be unambiguously represented as a string by specifying the path to the item. The completion is then performed one level at a time.

Let’s take the example of a user typing in a file system path. The model is a (hierarchical) QFileSystemModel . The completion occurs for every element in the path. For example, if the current text is C:\Wind, QCompleter might suggest Windows to complete the current path element. Similarly, if the current text is C:\Windows\Sy, QCompleter might suggest System.

For this kind of completion to work, QCompleter needs to be able to split the path into a list of strings that are matched at each level. For C:\Windows\Sy, it needs to be split as “C:”, “Windows” and “Sy”. The default implementation of splitPath() , splits the completionPrefix using separator() if the model is a QFileSystemModel .

To provide completions, QCompleter needs to know the path from an index. This is provided by pathFromIndex() . The default implementation of pathFromIndex() , returns the data for the edit role for list models and the absolute file path if the mode is a QFileSystemModel .

See also

QAbstractItemModel QLineEdit QComboBox Completer Example

class PySide6.QtWidgets.QCompleter(model[, parent=None])¶

PySide6.QtWidgets.QCompleter([parent=None])

PySide6.QtWidgets.QCompleter(completions[, parent=None])

Parameters

model – PySide6.QtCore.QAbstractItemModel
completions – list of strings
parent – PySide6.QtCore.QObject

Constructs a completer object with the given parent that provides completions from the specified model.

Constructs a completer object with the given parent.

Constructs a QCompleter object with the given parent that uses the specified list as a source of possible completions.

PySide6.QtWidgets.QCompleter.CompletionMode¶

This enum specifies how completions are provided to the user.

Constant

Description

QCompleter.PopupCompletion

Current completions are displayed in a popup window.

QCompleter.InlineCompletion

Completions appear inline (as selected text).

QCompleter.UnfilteredPopupCompletion

All possible completions are displayed in a popup window with the most likely suggestion indicated as current.

See also

setCompletionMode()

PySide6.QtWidgets.QCompleter.ModelSorting¶

This enum specifies how the items in the model are sorted.

Constant

Description

QCompleter.UnsortedModel

The model is unsorted.

QCompleter.CaseSensitivelySortedModel

The model is sorted case sensitively.

QCompleter.CaseInsensitivelySortedModel

The model is sorted case insensitively.

See also

setModelSorting()

PySide6.QtWidgets.QCompleter.activated(index)¶

Parameters: index – PySide6.QtCore.QModelIndex

PySide6.QtWidgets.QCompleter.activated(text)

Parameters: text – str

PySide6.QtWidgets.QCompleter.caseSensitivity()¶

Return type: CaseSensitivity

This property holds the case sensitivity of the matching.

The default value is Qt::CaseSensitive.

See also

completionColumn completionRole modelSorting filterMode

PySide6.QtWidgets.QCompleter.complete([rect=QRect()])¶

Parameters: rect – PySide6.QtCore.QRect

For PopupCompletion and QCompletion::UnfilteredPopupCompletion modes, calling this function displays the popup displaying the current completions. By default, if rect is not specified, the popup is displayed on the bottom of the widget() . If rect is specified the popup is displayed on the left edge of the rectangle.

For InlineCompletion mode, the highlighted() signal is fired with the current completion.

PySide6.QtWidgets.QCompleter.completionColumn()¶

Return type: int

This property holds the column in the model in which completions are searched for..

If the popup() is a QListView , it is automatically setup to display this column.

By default, the match column is 0.

See also

completionRole caseSensitivity

PySide6.QtWidgets.QCompleter.completionCount()¶

Return type: int

Returns the number of completions for the current prefix. For an unsorted model with a large number of items this can be expensive. Use setCurrentRow() and currentCompletion() to iterate through all the completions.

PySide6.QtWidgets.QCompleter.completionMode()¶

Return type: CompletionMode

This property holds how the completions are provided to the user.

The default value is PopupCompletion .

PySide6.QtWidgets.QCompleter.completionModel()¶

Return type: PySide6.QtCore.QAbstractItemModel

Returns the completion model. The completion model is a read-only list model that contains all the possible matches for the current completion prefix. The completion model is auto-updated to reflect the current completions.

Note

The return value of this function is defined to be an QAbstractItemModel purely for generality. This actual kind of model returned is an instance of an QAbstractProxyModel subclass.

Table of Contents

Previous topic

Next topic