QCompleter¶

Synopsis¶

Functions¶

def caseSensitivity ()
def completionColumn ()
def completionCount ()
def completionMode ()
def completionModel ()
def completionPrefix ()
def completionRole ()
def currentCompletion ()
def currentIndex ()
def currentRow ()
def maxVisibleItems ()
def model ()
def modelSorting ()
def popup ()
def setCaseSensitivity (caseSensitivity)
def setCompletionColumn (column)
def setCompletionMode (mode)
def setCompletionRole (role)
def setCurrentRow (row)
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¶

The PySide.QtGui.QCompleter class provides completions based on an item model.

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

Basic Usage¶

A PySide.QtGui.QCompleter is used typically with a PySide.QtGui.QLineEdit or PySide.QtGui.QComboBox . For example, here’s how to provide auto completions from a simple word list in a PySide.QtGui.QLineEdit :
wordList = ["alpha", "omega", "omicron", "zeta"]

lineEdit = QLineEdit(self)

completer = QCompleter(wordList, self)
completer.setCaseSensitivity(Qt.CaseInsensitive)
lineEdit.setCompleter(completer)
A PySide.QtGui.QFileSystemModel can be used to provide auto completion of file names. For example:
completer = QCompleter(self)
completer.setModel(QDirModel(completer))
lineEdit.setCompleter(completer)
To set the model on which PySide.QtGui.QCompleter should operate, call PySide.QtGui.QCompleter.setModel() . By default, PySide.QtGui.QCompleter will attempt to match the completion prefix (i.e., the word that the user has started typing) against the Qt.EditRole data stored in column 0 in the model case sensitively. This can be changed using PySide.QtGui.QCompleter.setCompletionRole() , PySide.QtGui.QCompleter.setCompletionColumn() , and PySide.QtGui.QCompleter.setCaseSensitivity() .

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

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 PySide.QtGui.QCompleter.completionMode() determines the mode used to provide completions to the user.

Iterating Through Completions¶

To retrieve a single candidate string, call PySide.QtGui.QCompleter.setCompletionPrefix() with the text that needs to be completed and call PySide.QtGui.QCompleter.currentCompletion() . You can iterate through the list of completions as below:
i = 0
while completer.setCurrentRow(i):
    print "%s is match number %d" % (completer.currentCompletion(), i)
    i += 1
PySide.QtGui.QCompleter.completionCount() returns the total number of completions for the current prefix. PySide.QtGui.QCompleter.completionCount() should be avoided when possible, since it requires a scan of the entire model.

The Completion Model¶

PySide.QtGui.QCompleter.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 PySide.QtGui.QCompleter.setCompletionPrefix() automatically refreshes the completion model.

Handling Tree Models¶

PySide.QtGui.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) PySide.QtGui.QFileSystemModel . The completion occurs for every element in the path. For example, if the current text is C:\Wind , PySide.QtGui.QCompleter might suggest Windows to complete the current path element. Similarly, if the current text is C:\Windows\Sy , PySide.QtGui.QCompleter might suggest System .

For this kind of completion to work, PySide.QtGui.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 PySide.QtGui.QCompleter.splitPath() , splits the PySide.QtGui.QCompleter.completionPrefix() using QDir.separator() if the model is a PySide.QtGui.QFileSystemModel .

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

See also

PySide.QtCore.QAbstractItemModel PySide.QtGui.QLineEdit PySide.QtGui.QComboBox Completer Example

class PySide.QtGui.QCompleter(model[, parent=None])¶

class PySide.QtGui.QCompleter([parent=None])

class PySide.QtGui.QCompleter(completions[, parent=None])

Parameters:	completions – list of strings model – `PySide.QtCore.QAbstractItemModel` parent – `PySide.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 PySide.QtGui.QCompleter object with the given parent that uses the specified list as a source of possible completions.

PySide.QtGui.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.

PySide.QtGui.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.

PySide.QtGui.QCompleter.activated(text)¶

Parameters:	text – unicode

PySide.QtGui.QCompleter.activated(index)

Parameters:	index – `PySide.QtCore.QModelIndex`

PySide.QtGui.QCompleter.caseSensitivity()¶

Return type:	`PySide.QtCore.Qt.CaseSensitivity`

This property holds the case sensitivity of the matching.

The default is Qt.CaseSensitive .

PySide.QtGui.QCompleter.complete([rect=QRect()])¶

Parameters:	rect – `PySide.QtCore.QRect`

For QCompleter.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 PySide.QtGui.QCompleter.widget() . If rect is specified the popup is displayed on the left edge of the rectangle.

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

PySide.QtGui.QCompleter.completionColumn()¶

Return type:	`PySide.QtCore.int`

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

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

By default, the match column is 0.

PySide.QtGui.QCompleter.completionCount()¶

Return type:	`PySide.QtCore.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 PySide.QtGui.QCompleter.setCurrentRow() and PySide.QtGui.QCompleter.currentCompletion() to iterate through all the completions.

PySide.QtGui.QCompleter.completionMode()¶

Return type:	`PySide.QtGui.QCompleter.CompletionMode`

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

The default value is QCompleter.PopupCompletion .

PySide.QtGui.QCompleter.completionModel()¶

Return type:	`PySide.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 PySide.QtCore.QAbstractItemModel purely for generality. This actual kind of model returned is an instance of an PySide.QtGui.QAbstractProxyModel subclass.

PySide.QtGui.QCompleter.completionPrefix()¶

Return type:	unicode

This property holds the completion prefix used to provide completions..

The PySide.QtGui.QCompleter.completionModel() is updated to reflect the list of possible matches for prefix .

PySide.QtGui.QCompleter.completionRole()¶

Return type:	`PySide.QtCore.int`

This property holds the item role to be used to query the contents of items for matching..

The default role is Qt.EditRole .

PySide.QtGui.QCompleter.currentCompletion()¶

Return type:	unicode

Returns the current completion string. This includes the PySide.QtGui.QCompleter.completionPrefix() . When used alongside PySide.QtGui.QCompleter.setCurrentRow() , it can be used to iterate through all the matches.

PySide.QtGui.QCompleter.currentIndex()¶

Return type:	`PySide.QtCore.QModelIndex`

Returns the model index of the current completion in the PySide.QtGui.QCompleter.completionModel() .

PySide.QtGui.QCompleter.currentRow()¶

Return type:	`PySide.QtCore.int`

Returns the current row.

PySide.QtGui.QCompleter.highlighted(text)¶

Parameters:	text – unicode

PySide.QtGui.QCompleter.highlighted(index)

Parameters:	index – `PySide.QtCore.QModelIndex`

PySide.QtGui.QCompleter.maxVisibleItems()¶

Return type:	`PySide.QtCore.int`

This property holds the maximum allowed size on screen of the completer, measured in items.

By default, this property has a value of 7.

PySide.QtGui.QCompleter.model()¶

Return type:	`PySide.QtCore.QAbstractItemModel`

Returns the model that provides completion strings.

PySide.QtGui.QCompleter.modelSorting()¶

Return type:	`PySide.QtGui.QCompleter.ModelSorting`

This property holds the way the model is sorted.

By default, no assumptions are made about the order of the items in the model that provides the completions.

If the model’s data for the PySide.QtGui.QCompleter.completionColumn() and PySide.QtGui.QCompleter.completionRole() is sorted in ascending order, you can set this property to CaseSensitivelySortedModel or CaseInsensitivelySortedModel . On large models, this can lead to significant performance improvements because the completer object can then use a binary search algorithm instead of linear search algorithm.

The sort order (i.e ascending or descending order) of the model is determined dynamically by inspecting the contents of the model.

Note

The performance improvements described above cannot take place when the completer’s PySide.QtGui.QCompleter.caseSensitivity() is different to the case sensitivity used by the model’s when sorting.

See also

PySide.QtGui.QCompleter.setCaseSensitivity() QCompleter.ModelSorting

PySide.QtGui.QCompleter.pathFromIndex(index)¶

Parameters:	index – `PySide.QtCore.QModelIndex`
Return type:	unicode

Returns the path for the given index . The completer object uses this to obtain the completion text from the underlying model.

The default implementation returns the edit role of the item for list models. It returns the absolute file path if the model is a PySide.QtGui.QFileSystemModel .

See also

PySide.QtGui.QCompleter.splitPath()

PySide.QtGui.QCompleter.popup()¶

Return type:	`PySide.QtGui.QAbstractItemView`

Returns the popup used to display completions.

See also

PySide.QtGui.QCompleter.setPopup()

PySide.QtGui.QCompleter.setCaseSensitivity(caseSensitivity)¶

Parameters:	caseSensitivity – `PySide.QtCore.Qt.CaseSensitivity`

This property holds the case sensitivity of the matching.

The default is Qt.CaseSensitive .

PySide.QtGui.QCompleter.setCompletionColumn(column)¶

Parameters:	column – `PySide.QtCore.int`

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

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

By default, the match column is 0.

PySide.QtGui.QCompleter.setCompletionMode(mode)¶

Parameters:	mode – `PySide.QtGui.QCompleter.CompletionMode`

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

The default value is QCompleter.PopupCompletion .

PySide.QtGui.QCompleter.setCompletionPrefix(prefix)¶

Parameters:	prefix – unicode

This property holds the completion prefix used to provide completions..

The PySide.QtGui.QCompleter.completionModel() is updated to reflect the list of possible matches for prefix .

PySide.QtGui.QCompleter.setCompletionRole(role)¶

Parameters:	role – `PySide.QtCore.int`

This property holds the item role to be used to query the contents of items for matching..

The default role is Qt.EditRole .

PySide.QtGui.QCompleter.setCurrentRow(row)¶

Parameters:	row – `PySide.QtCore.int`
Return type:	`PySide.QtCore.bool`

Sets the current row to the row specified. Returns true if successful; otherwise returns false.

This function may be used along with PySide.QtGui.QCompleter.currentCompletion() to iterate through all the possible completions.

PySide.QtGui.QCompleter.setMaxVisibleItems(maxItems)¶

Parameters:	maxItems – `PySide.QtCore.int`

This property holds the maximum allowed size on screen of the completer, measured in items.

By default, this property has a value of 7.

PySide.QtGui.QCompleter.setModel(c)¶

Parameters:	c – `PySide.QtCore.QAbstractItemModel`

Sets the model which provides completions to model . The model can be list model or a tree model. If a model has been already previously set and it has the PySide.QtGui.QCompleter as its parent, it is deleted.

For convenience, if model is a PySide.QtGui.QFileSystemModel , PySide.QtGui.QCompleter switches its PySide.QtGui.QCompleter.caseSensitivity() to Qt.CaseInsensitive on Windows and Qt.CaseSensitive on other platforms.

PySide.QtGui.QCompleter.setModelSorting(sorting)¶

Parameters:	sorting – `PySide.QtGui.QCompleter.ModelSorting`

This property holds the way the model is sorted.

By default, no assumptions are made about the order of the items in the model that provides the completions.

If the model’s data for the PySide.QtGui.QCompleter.completionColumn() and PySide.QtGui.QCompleter.completionRole() is sorted in ascending order, you can set this property to CaseSensitivelySortedModel or CaseInsensitivelySortedModel . On large models, this can lead to significant performance improvements because the completer object can then use a binary search algorithm instead of linear search algorithm.

The sort order (i.e ascending or descending order) of the model is determined dynamically by inspecting the contents of the model.

Note

The performance improvements described above cannot take place when the completer’s PySide.QtGui.QCompleter.caseSensitivity() is different to the case sensitivity used by the model’s when sorting.

See also

PySide.QtGui.QCompleter.setCaseSensitivity() QCompleter.ModelSorting

PySide.QtGui.QCompleter.setPopup(popup)¶

Parameters:	popup – `PySide.QtGui.QAbstractItemView`

Sets the popup used to display completions to popup . PySide.QtGui.QCompleter takes ownership of the view.

A PySide.QtGui.QListView is automatically created when the PySide.QtGui.QCompleter.completionMode() is set to QCompleter.PopupCompletion or QCompleter.UnfilteredPopupCompletion . The default popup displays the PySide.QtGui.QCompleter.completionColumn() .

Ensure that this function is called before the view settings are modified. This is required since view’s properties may require that a model has been set on the view (for example, hiding columns in the view requires a model to be set on the view).

See also

PySide.QtGui.QCompleter.popup()

PySide.QtGui.QCompleter.setWidget(widget)¶

Parameters:	widget – `PySide.QtGui.QWidget`

Sets the widget for which completion are provided for to widget . This function is automatically called when a PySide.QtGui.QCompleter is set on a PySide.QtGui.QLineEdit using QLineEdit.setCompleter() or on a PySide.QtGui.QComboBox using QComboBox.setCompleter() . The widget needs to be set explicitly when providing completions for custom widgets.

PySide.QtGui.QCompleter.setWrapAround(wrap)¶

Parameters:	wrap – `PySide.QtCore.bool`

This property holds the completions wrap around when navigating through items.

The default is true.

PySide.QtGui.QCompleter.splitPath(path)¶

Parameters:	path – unicode
Return type:	list of strings

Splits the given path into strings that are used to match at each level in the PySide.QtGui.QCompleter.model() .

The default implementation of PySide.QtGui.QCompleter.splitPath() splits a file system path based on QDir.separator() when the sourceModel() is a PySide.QtGui.QFileSystemModel .

When used with list models, the first item in the returned list is used for matching.

See also

PySide.QtGui.QCompleter.pathFromIndex() Handling Tree Models

PySide.QtGui.QCompleter.widget()¶

Return type:	`PySide.QtGui.QWidget`

Returns the widget for which the completer object is providing completions.

See also

PySide.QtGui.QCompleter.setWidget()

PySide.QtGui.QCompleter.wrapAround()¶

Return type:	`PySide.QtCore.bool`

This property holds the completions wrap around when navigating through items.

The default is true.

Table Of Contents

Previous topic

Next topic

QCompleter¶

Synopsis¶

Functions¶

Virtual functions¶

Slots¶

Signals¶

Detailed Description¶

Basic Usage¶

Iterating Through Completions¶

The Completion Model¶

Handling Tree Models¶

Table Of Contents

Previous topic

Next topic

Quick search

QCompleter¶

Synopsis¶

Functions¶

Virtual functions¶

Slots¶

Signals¶

Detailed Description¶

Basic Usage¶

Iterating Through Completions¶

The Completion Model¶

Handling Tree Models¶