QCompleter 类提供基于项模型的补全。 更多...
头: | #include <QCompleter> |
CMake: |
find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
qmake: | QT += widgets |
继承: | QObject |
enum | CompletionMode { PopupCompletion, InlineCompletion, UnfilteredPopupCompletion } |
enum | ModelSorting { UnsortedModel, CaseSensitivelySortedModel, CaseInsensitivelySortedModel } |
|
|
QCompleter (QObject * parent = nullptr) | |
QCompleter (QAbstractItemModel * model , QObject * parent = nullptr) | |
QCompleter (const QStringList & list , QObject * parent = nullptr) | |
virtual | ~QCompleter () override |
Qt::CaseSensitivity | caseSensitivity () const |
int | completionColumn () const |
int | completionCount () const |
QCompleter::CompletionMode | completionMode () const |
QAbstractItemModel * | completionModel () const |
QString | completionPrefix () const |
int | completionRole () const |
QString | currentCompletion () const |
QModelIndex | currentIndex () const |
int | currentRow () const |
Qt::MatchFlags | filterMode () const |
int | maxVisibleItems () const |
QAbstractItemModel * | model () const |
QCompleter::ModelSorting | modelSorting () const |
virtual QString | pathFromIndex (const QModelIndex & index ) const |
QAbstractItemView * | popup () const |
void | setCaseSensitivity (Qt::CaseSensitivity caseSensitivity ) |
void | setCompletionColumn (int column ) |
void | setCompletionMode (QCompleter::CompletionMode mode ) |
void | setCompletionRole (int role ) |
bool | setCurrentRow (int row ) |
void | setFilterMode (Qt::MatchFlags filterMode ) |
void | setMaxVisibleItems (int maxItems ) |
void | setModel (QAbstractItemModel * model ) |
void | setModelSorting (QCompleter::ModelSorting sorting ) |
void | setPopup (QAbstractItemView * popup ) |
void | setWidget (QWidget * widget ) |
virtual QStringList | splitPath (const QString & path ) const |
QWidget * | widget () const |
bool | wrapAround () const |
void | complete (const QRect & rect = QRect()) |
void | setCompletionPrefix (const QString & prefix ) |
void | setWrapAround (bool wrap ) |
void | activated (const QString & text ) |
void | activated (const QModelIndex & index ) |
void | highlighted (const QString & text ) |
void | highlighted (const QModelIndex & index ) |
virtual bool | event (QEvent * ev ) override |
virtual bool | eventFilter (QObject * o , QEvent * e ) override |
可以使用 QCompleter 为任何 Qt Widget 提供自动补全,譬如 QLineEdit and QComboBox 。当用户开始键入单词时,QCompleter 基于单词列表建议补全单词的可能方式。单词列表被提供作为 QAbstractItemModel 。(对于单词列表是静态的简单应用程序,可以传递 QStringList 给 QCompleter 的构造函数。)
QCompleter 通常用于 QLineEdit or QComboBox 。例如,这里是如何从简单单词列表提供自动补全在 QLineEdit :
QStringList wordList; wordList << "alpha" << "omega" << "omicron" << "zeta"; QLineEdit *lineEdit = new QLineEdit(this); QCompleter *completer = new QCompleter(wordList, this); completer->setCaseSensitivity(Qt::CaseInsensitive); lineEdit->setCompleter(completer);
A QFileSystemModel 可以被用于提供文件名自动补全。例如:
QCompleter *completer = new QCompleter(this); completer->setModel(new QFileSystemModel(completer)); lineEdit->setCompleter(completer);
要设置 QCompleter 应该操作的模型,调用 setModel ()。默认情况下,QCompleter 会试图匹配 补全前缀 (即:用户已开始键入的单词) 针对 Qt::EditRole 在区分大小写的模型中存储第 0 列数据。这可以被改变使用 setCompletionRole (), setCompletionColumn (),和 setCaseSensitivity ().
若模型按被用于补全的角色和列进行排序,可以调用 setModelSorting () 采有 QCompleter::CaseSensitivelySortedModel or QCompleter::CaseInsensitivelySortedModel 作为自变量。在大型模型上,这可以导致显著性能改进,因为 QCompleter 随后可以使用二进制搜索而不是线性搜索。二进制搜索才工作,当 filterMode is Qt::MatchStartsWith .
模型可以是 列表模型 , 表模型 ,或 树模型 。树模型补全稍微更涉及,且涵盖于 处理树模型 以下章节。
The completionMode () 确定用于向用户提供补全的方式。
要检索单候选字符串,调用 setCompletionPrefix () 采用需要被补全的文本,然后调用 currentCompletion ()。可以遍历补全列表,如下所示:
for (int i = 0; completer->setCurrentRow(i); i++) qDebug() << completer->currentCompletion() << " is match number " << i;
completionCount () 返回为当前前缀的补全总数。 completionCount () 应尽可能避免,因为它要求扫描整个模型。
completionModel () 返回包含为当前补全前缀的所有可能补全 (按照它们在模型中的出现次序) 的列表模型。此模型可以被用来在自定义视图中显示当前补全。调用 setCompletionPrefix () 自动刷新补全模型。
QCompleter 可以在树模型中查找补全,假定可以通过指定项路径把任何项 (或子项或子子项) 明确表示为字符串。然后一次履行一个级别的补全。
让我们以用户键入文件系统路径为例。模型是 (分层)
QFileSystemModel
。补全发生在每路径元素。例如,若当前文本是
C:\Wind
,QCompleter 可能建议
Windows
去补全当前路径元素。同样,若当前文本是
C:\Windows\Sy
,QCompleter 可能建议
系统
.
对于这种补全工作,QCompleter 需要把路径分割成能够在每级别匹配的字符串列表。对于
C:\Windows\Sy
,它需要被分割成 C: Windows 及 Sy。默认实现的
splitPath
(),分割
completionPrefix
使用
QDir::separator
() 若模型是
QFileSystemModel
.
为提供补全,QCompleter 需要知道来自索引的路径。这被提供由 pathFromIndex ()。默认实现的 pathFromIndex (),返回数据为 编辑角色 的列表模型和绝对文件路径,若模式为 QFileSystemModel .
另请参阅 QAbstractItemModel , QLineEdit , QComboBox ,和 补全器范例 .
此枚举指定如何向用户提供补全。
常量 | 值 | 描述 |
---|---|---|
QCompleter::PopupCompletion
|
0
|
当前补全被显示在弹出窗口中。 |
QCompleter::InlineCompletion
|
2
|
补全内联出现 (作为选中文本)。 |
QCompleter::UnfilteredPopupCompletion
|
1
|
所有可能的补全均被显示在弹出窗口中,采用最有可能建议指示作为当前。 |
另请参阅 setCompletionMode ().
此枚举指定如何对模型项进行排序。
常量 | 值 | 描述 |
---|---|---|
QCompleter::UnsortedModel
|
0
|
模型不排序。 |
QCompleter::CaseSensitivelySortedModel
|
1
|
模型排序区分大小写。 |
QCompleter::CaseInsensitivelySortedModel
|
2
|
模型排序不区分大小写。 |
另请参阅 setModelSorting ().
此特性保持匹配的大小写敏感性
默认值为
Qt::CaseSensitive
.
访问函数:
Qt::CaseSensitivity | caseSensitivity () const |
void | setCaseSensitivity (Qt::CaseSensitivity caseSensitivity ) |
另请参阅 completionColumn , completionRole , modelSorting ,和 filterMode .
此特性保持在其中搜索完成的模型列。
若 popup () 是 QListView , it is automatically setup to display this column.
默认情况下,匹配列为 0。
访问函数:
int | completionColumn () const |
void | setCompletionColumn (int column ) |
另请参阅 completionRole and caseSensitivity .
如何向用户提供补全
默认值为 QCompleter::PopupCompletion .
访问函数:
QCompleter::CompletionMode | completionMode () const |
void | setCompletionMode (QCompleter::CompletionMode mode ) |
此特性保持用于提供补全的补全前缀。
The completionModel () 被更新以反映可能匹配的列表为 prefix .
访问函数:
QString | completionPrefix () const |
void | setCompletionPrefix (const QString & prefix ) |
此特性保持被用于查询匹配项内容的项角色。
默认角色为 Qt::EditRole .
访问函数:
int | completionRole () const |
void | setCompletionRole (int role ) |
另请参阅 completionColumn and caseSensitivity .
This property controls how filtering is performed.
若 filterMode 被设为 Qt::MatchStartsWith , only those entries that start with the typed characters will be displayed. Qt::MatchContains will display the entries that contain the typed characters, and Qt::MatchEndsWith the ones that end with the typed characters.
Setting filterMode to any other
Qt::MatchFlag
will issue a warning, and no action will be performed. Because of this, the
Qt::MatchCaseSensitive
flag has no effect. Use the
caseSensitivity
property to control case sensitivity.
默认模式为 Qt::MatchStartsWith .
访问函数:
Qt::MatchFlags | filterMode () const |
void | setFilterMode (Qt::MatchFlags filterMode ) |
另请参阅 caseSensitivity .
此特性保持补全器屏幕的最大允许尺寸 (以项为单位度量)
默认情况下,此属性拥有 7 值。
访问函数:
int | maxVisibleItems () const |
void | setMaxVisibleItems (int maxItems ) |
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 completionColumn () 和 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.
注意: The performance improvements described above cannot take place when the completer's caseSensitivity is different to the case sensitivity used by the model's when sorting.
访问函数:
QCompleter::ModelSorting | modelSorting () const |
void | setModelSorting (QCompleter::ModelSorting sorting ) |
另请参阅 setCaseSensitivity () 和 QCompleter::ModelSorting .
This property holds the completions wrap around when navigating through items
默认为 true。
访问函数:
bool | wrapAround () const |
void | setWrapAround (bool wrap ) |
构造补全器对象采用给定 parent .
构造补全器对象采用给定 parent 提供补全来自指定 model .
构造 QCompleter 对象采用给定 parent 使用指定 list 作为可能的补全源。
[override virtual]
QCompleter::
~QCompleter
()
销毁补全器对象。
[signal]
void
QCompleter::
activated
(const
QString
&
text
)
此信号被发送当项在 popup () 被用户激活 (通过点击或按下回车键)。项的 text 有给定。
注意: 信号 activated 在此类中被重载。通过使用函数指针句法连接到此信号,Qt 提供用于获得如此范例展示的函数指针的方便帮助程序:
connect(completer, QOverload<const QString &>::of(&QCompleter::activated), [=](const QString &text){ /* ... */ });
[signal]
void
QCompleter::
activated
(const
QModelIndex
&
index
)
此信号被发送当项在 popup () 被用户激活。(通过点击或按下回车键)。项的 index 在 completionModel () 有给定。
注意: 信号 activated 在此类中被重载。通过使用函数指针句法连接到此信号,Qt 提供用于获得如此范例展示的函数指针的方便帮助程序:
connect(completer, QOverload<const QModelIndex &>::of(&QCompleter::activated), [=](const QModelIndex &index){ /* ... */ });
[slot]
void
QCompleter::
complete
(const
QRect
&
rect
= QRect())
For QCompleter::PopupCompletion 和 QCompletion::UnfilteredPopupCompletion 模式,调用此函数显示当前补全的弹出窗口。默认情况下,若 rect 未指定,弹出窗口显示在底部对于 widget ()。若 rect 被指定,弹出窗口显示在矩形的左边缘。
For QCompleter::InlineCompletion 模式, highlighted () 信号被激发采用当前补全。
返回为当前前缀的补全数。对于具有大量项的未排序模型,这可能是昂贵的。使用 setCurrentRow () 和 currentCompletion () 去遍历所有补全。
返回补全模型。补全模型是包含为当前补全前缀的所有可能匹配的只读列表模型。补全模型被自动更新以反映当前补全。
注意: 此函数的返回值被定义为 QAbstractItemModel 纯粹为通用性。这种实际返回的模型是实例对于 QAbstractProxyModel 子类。
另请参阅 completionPrefix and model ().
返回当前补全字符串。这包括 completionPrefix 。当同时使用 setCurrentRow (),它可以被用于遍历所有匹配。
另请参阅 setCurrentRow () 和 currentIndex ().
返回当前补全的模型索引在 completionModel ().
另请参阅 setCurrentRow (), currentCompletion (),和 model ().
返回当前行。
另请参阅 setCurrentRow ().
[override virtual protected]
bool
QCompleter::
event
(
QEvent
*
ev
)
重实现: QObject::event (QEvent *e).
[override virtual protected]
bool
QCompleter::
eventFilter
(
QObject
*
o
,
QEvent
*
e
)
重实现: QObject::eventFilter (QObject *watched, QEvent *event).
[signal]
void
QCompleter::
highlighted
(const
QString
&
text
)
此信号被发送当项在 popup () 被高亮由用户。它也被发送若 complete () 被调用采用 completionMode () 设为 QCompleter::InlineCompletion 。项的 text 有给定。
注意: 信号 highlighted 在此类中被重载。通过使用函数指针句法连接到此信号,Qt 提供用于获得如此范例展示的函数指针的方便帮助程序:
connect(completer, QOverload<const QString &>::of(&QCompleter::highlighted), [=](const QString &text){ /* ... */ });
[signal]
void
QCompleter::
highlighted
(const
QModelIndex
&
index
)
此信号被发送当项在 popup () 被高亮由用户。它也被发送若 complete () 被调用采用 completionMode () 设为 QCompleter::InlineCompletion 。项的 index 在 completionModel () 有给定。
注意: 信号 highlighted 在此类中被重载。通过使用函数指针句法连接到此信号,Qt 提供用于获得如此范例展示的函数指针的方便帮助程序:
connect(completer, QOverload<const QModelIndex &>::of(&QCompleter::highlighted), [=](const QModelIndex &index){ /* ... */ });
返回提供补全字符串的模型。
另请参阅 setModel () 和 completionModel ().
[virtual]
QString
QCompleter::
pathFromIndex
(const
QModelIndex
&
index
) const
返回路径为给定 index 。补全器对象使用此,以从底层模型中获得补全文本。
默认实现返回 编辑角色 的列表模型项。它返回绝对文件路径,若模型是 QFileSystemModel .
另请参阅 splitPath ().
返回用于显示补全的弹出窗口。
另请参阅 setPopup ().
把当前行设为
row
指定。返回
true
若成功;否则返回
false
.
此函数可以被使用沿着 currentCompletion () 去遍历所有可能的补全。
另请参阅 currentRow (), currentCompletion (),和 completionCount ().
把提供补全的模型设为 model 。 model 可以是列表模型 (或树模型)。若模型事先已经被设置,且它有 QCompleter 作为其父级,它将被删除。
为方便起见,若 model 是 QFileSystemModel , QCompleter 切换其 caseSensitivity to Qt::CaseInsensitive 在 Windows 和 Qt::CaseSensitive 在其它平台。
另请参阅 completionModel (), modelSorting ,和 处理树模型 .
把用于显示补全的弹出窗口设为 popup . QCompleter 拥有视图的所有权。
A QListView 被自动创建当 completionMode () 被设为 QCompleter::PopupCompletion or QCompleter::UnfilteredPopupCompletion 。默认弹出窗口显示 completionColumn ().
确保此函数被调用,在视图设置被修改之前。这是必需的,因为视图的特性可能要求在视图上设置模型 (例如:隐藏视图列要求在视图上设置模型)。
另请参阅 popup ().
把为其提供补全的小部件设为 widget 。此函数被自动调用当 QCompleter 被设置在 QLineEdit 使用 QLineEdit::setCompleter () 或在 QComboBox 使用 QComboBox::setCompleter ()。小部件需要被明确设置,当为自定义小部件提供补全时。
另请参阅 widget (), setModel (),和 setPopup ().
[virtual]
QStringList
QCompleter::
splitPath
(const
QString
&
path
) const
分割给定 path 成字符串,用于每级匹配在 model ().
默认实现的 splitPath() 分割文件系统路径基于 QDir::separator () 当 sourceModel() 是 QFileSystemModel .
当用于列表模型时,返回列表中的第一项被用于匹配。
另请参阅 pathFromIndex () 和 处理树模型 .
返回补全器对象正为其提供补全的 Widget。
另请参阅 setWidget ().