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 asQLineEdit
andQComboBox
. 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 aQAbstractItemModel
. (For simple applications, where the word list is static, you can pass aQStringList
toQCompleter
‘s constructor.)
Basic Usage¶
A
QCompleter
is used typically with aQLineEdit
orQComboBox
. For example, here’s how to provide auto completions from a simple word list in aQLineEdit
: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(QDirModel(completer)) lineEdit.setCompleter(completer)To set the model on which
QCompleter
should operate, callsetModel()
. By default,QCompleter
will attempt to match thecompletion prefix
(i.e., the word that the user has started typing) against theEditRole
data stored in column 0 in the model case sensitively. This can be changed usingsetCompletionRole()
,setCompletionColumn()
, andsetCaseSensitivity()
.If the model is sorted on the column and role that are used for completion, you can call
setModelSorting()
with eitherCaseSensitivelySortedModel
orCaseInsensitivelySortedModel
as the argument. On large models, this can lead to significant performance improvements, becauseQCompleter
can then use binary search instead of linear search. The binary search only works when thefilterMode
isMatchStartsWith
.The model can be a
list model
, atable model
, or atree model
. Completion on tree models is slightly more involved and is covered in theHandling 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 callcurrentCompletion()
. 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
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. CallingsetCompletionPrefix()
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 isC:\Wind
,QCompleter
might suggestWindows
to complete the current path element. Similarly, if the current text isC:\Windows\Sy
,QCompleter
might suggestSystem
.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. ForC:\Windows\Sy
, it needs to be split as “C:”, “Windows” and “Sy”. The default implementation ofsplitPath()
, splits thecompletionPrefix
usingseparator()
if the model is aQFileSystemModel
.To provide completions,
QCompleter
needs to know the path from an index. This is provided bypathFromIndex()
. The default implementation ofpathFromIndex()
, returns the data for theedit role
for list models and the absolute file path if the mode is aQFileSystemModel
.
-
class
QCompleter
(model[, parent=None])¶ QCompleter([parent=None])
QCompleter(completions[, parent=None])
- param parent
QObject
- param model
QAbstractItemModel
- param completions
list of strings
Constructs a completer object with the given
parent
that provides completions from the specifiedmodel
.Constructs a completer object with the given
parent
.
-
PySide2.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
-
PySide2.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
-
PySide2.QtWidgets.QCompleter.
activated
(index)¶ - Parameters
index –
QModelIndex
-
PySide2.QtWidgets.QCompleter.
activated
(text) - Parameters
text – unicode
-
PySide2.QtWidgets.QCompleter.
caseSensitivity
()¶ - Return type
CaseSensitivity
See also
-
PySide2.QtWidgets.QCompleter.
complete
([rect=QRect()])¶ - Parameters
rect –
QRect
For
PopupCompletion
and QCompletion::UnfilteredPopupCompletion modes, calling this function displays the popup displaying the current completions. By default, ifrect
is not specified, the popup is displayed on the bottom of thewidget()
. Ifrect
is specified the popup is displayed on the left edge of the rectangle.For
InlineCompletion
mode, thehighlighted()
signal is fired with the current completion.
-
PySide2.QtWidgets.QCompleter.
completionColumn
()¶ - Return type
int
See also
-
PySide2.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()
andcurrentCompletion()
to iterate through all the completions.
-
PySide2.QtWidgets.QCompleter.
completionMode
()¶ - Return type
See also
-
PySide2.QtWidgets.QCompleter.
completionModel
()¶ - Return type
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 anQAbstractProxyModel
subclass.See also
-
PySide2.QtWidgets.QCompleter.
completionPrefix
()¶ - Return type
unicode
See also
-
PySide2.QtWidgets.QCompleter.
completionRole
()¶ - Return type
int
See also
-
PySide2.QtWidgets.QCompleter.
currentCompletion
()¶ - Return type
unicode
Returns the current completion string. This includes the
completionPrefix
. When used alongsidesetCurrentRow()
, it can be used to iterate through all the matches.See also
-
PySide2.QtWidgets.QCompleter.
currentIndex
()¶ - Return type
QModelIndex
Returns the model index of the current completion in the
completionModel()
.See also
-
PySide2.QtWidgets.QCompleter.
currentRow
()¶ - Return type
int
Returns the current row.
See also
-
PySide2.QtWidgets.QCompleter.
filterMode
()¶ - Return type
MatchFlags
See also
-
PySide2.QtWidgets.QCompleter.
highlighted
(index)¶ - Parameters
index –
QModelIndex
-
PySide2.QtWidgets.QCompleter.
highlighted
(text) - Parameters
text – unicode
-
PySide2.QtWidgets.QCompleter.
maxVisibleItems
()¶ - Return type
int
See also
-
PySide2.QtWidgets.QCompleter.
model
()¶ - Return type
QAbstractItemModel
Returns the model that provides completion strings.
See also
-
PySide2.QtWidgets.QCompleter.
modelSorting
()¶ - Return type
See also
-
PySide2.QtWidgets.QCompleter.
pathFromIndex
(index)¶ - Parameters
index –
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 aQFileSystemModel
.See also
-
PySide2.QtWidgets.QCompleter.
popup
()¶ - Return type
Returns the popup used to display completions.
See also
-
PySide2.QtWidgets.QCompleter.
setCaseSensitivity
(caseSensitivity)¶ - Parameters
caseSensitivity –
CaseSensitivity
See also
-
PySide2.QtWidgets.QCompleter.
setCompletionColumn
(column)¶ - Parameters
column –
int
See also
-
PySide2.QtWidgets.QCompleter.
setCompletionMode
(mode)¶ - Parameters
mode –
CompletionMode
See also
-
PySide2.QtWidgets.QCompleter.
setCompletionPrefix
(prefix)¶ - Parameters
prefix – unicode
See also
-
PySide2.QtWidgets.QCompleter.
setCompletionRole
(role)¶ - Parameters
role –
int
See also
-
PySide2.QtWidgets.QCompleter.
setCurrentRow
(row)¶ - Parameters
row –
int
- Return type
bool
Sets the current row to the
row
specified. Returnstrue
if successful; otherwise returnsfalse
.This function may be used along with
currentCompletion()
to iterate through all the possible completions.
-
PySide2.QtWidgets.QCompleter.
setFilterMode
(filterMode)¶ - Parameters
filterMode –
MatchFlags
See also
-
PySide2.QtWidgets.QCompleter.
setMaxVisibleItems
(maxItems)¶ - Parameters
maxItems –
int
See also
-
PySide2.QtWidgets.QCompleter.
setModel
(c)¶ - Parameters
c –
QAbstractItemModel
Sets the model which provides completions to
model
. Themodel
can be list model or a tree model. If a model has been already previously set and it has theQCompleter
as its parent, it is deleted.For convenience, if
model
is aQFileSystemModel
,QCompleter
switches itscaseSensitivity
toCaseInsensitive
on Windows andCaseSensitive
on other platforms.See also
completionModel()
modelSorting
Handling Tree Models
-
PySide2.QtWidgets.QCompleter.
setModelSorting
(sorting)¶ - Parameters
sorting –
ModelSorting
See also
-
PySide2.QtWidgets.QCompleter.
setPopup
(popup)¶ - Parameters
popup –
QAbstractItemView
Sets the popup used to display completions to
popup
.QCompleter
takes ownership of the view.A
QListView
is automatically created when thecompletionMode()
is set toPopupCompletion
orUnfilteredPopupCompletion
. The default popup displays thecompletionColumn()
.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
-
PySide2.QtWidgets.QCompleter.
setWidget
(widget)¶ - Parameters
widget –
QWidget
Sets the widget for which completion are provided for to
widget
. This function is automatically called when aQCompleter
is set on aQLineEdit
usingsetCompleter()
or on aQComboBox
usingsetCompleter()
. The widget needs to be set explicitly when providing completions for custom widgets.See also
-
PySide2.QtWidgets.QCompleter.
setWrapAround
(wrap)¶ - Parameters
wrap –
bool
See also
-
PySide2.QtWidgets.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 themodel()
.The default implementation of splits a file system path based on
separator()
when the sourceModel() is aQFileSystemModel
.When used with list models, the first item in the returned list is used for matching.
See also
pathFromIndex()
Handling Tree Models
-
PySide2.QtWidgets.QCompleter.
widget
()¶ - Return type
Returns the widget for which the completer object is providing completions.
See also
-
PySide2.QtWidgets.QCompleter.
wrapAround
()¶ - Return type
bool
See also
© 2018 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.