QCompleter 类

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 }

特性

caseSensitivity : Qt::CaseSensitivity
completionColumn : int
completionMode : CompletionMode
completionPrefix : QString
completionRole : int

filterMode : Qt::MatchFlags
maxVisibleItems : int
modelSorting : ModelSorting
wrapAround : bool

公共函数

	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 ，和补全器范例 .

成员类型文档编制

enum QCompleter:: CompletionMode

此枚举指定如何向用户提供补全。

常量	值	描述
`QCompleter::PopupCompletion`	`0`	在弹出窗口中显示当前补全。
`QCompleter::InlineCompletion`	`2`	补全内联出现 (作为选中文本)。
`QCompleter::UnfilteredPopupCompletion`	`1`	在弹出窗口中显示所有可能的补全，采用如当前指示的最有可能建议。

另请参阅 setCompletionMode ().

enum QCompleter:: ModelSorting

此枚举指定如何对模型项进行排序。

常量	值	描述
`QCompleter::UnsortedModel`	`0`	模型不排序。
`QCompleter::CaseSensitivelySortedModel`	`1`	模型排序区分大小写。
`QCompleter::CaseInsensitivelySortedModel`	`2`	模型排序不区分大小写。

另请参阅 setModelSorting ().

特性文档编制

caseSensitivity : Qt::CaseSensitivity

此特性保持匹配的大小写敏感性

默认值为 Qt::CaseSensitive .

访问函数：

Qt::CaseSensitivity	caseSensitivity () const
void	setCaseSensitivity (Qt::CaseSensitivity caseSensitivity )

另请参阅 completionColumn , completionRole , modelSorting ，和 filterMode .

completionColumn : int

此特性保持在其中搜索补全的模型列。

若 popup () 是 QListView ，被自动设为显示此列。

默认情况下，匹配列为 0。

访问函数：

int	completionColumn () const
void	setCompletionColumn (int column )

另请参阅 completionRole and caseSensitivity .

completionMode : CompletionMode

如何向用户提供补全

默认值为 QCompleter::PopupCompletion .

访问函数：

QCompleter::CompletionMode	completionMode () const
void	setCompletionMode (QCompleter::CompletionMode mode )

completionPrefix : QString

此特性保持用于提供补全的补全前缀。

The completionModel () 被更新以反映可能匹配的列表为 prefix .

访问函数：

QString	completionPrefix () const
void	setCompletionPrefix (const QString & prefix )

completionRole : int

此特性保持用于查询匹配项内容的项角色。

默认角色为 Qt::EditRole .

访问函数：

int	completionRole () const
void	setCompletionRole (int role )

另请参阅 completionColumn and caseSensitivity .

filterMode : Qt::MatchFlags

此特性控制如何履行过滤。

若 filterMode 被设为 Qt::MatchStartsWith ，仅显示以键入字符开头的那些条目。 Qt::MatchContains 将显示包含键入字符的条目，和 Qt::MatchEndsWith 是以键入字符结尾的那些。

把 filterMode 设为任何其它 Qt::MatchFlag 将发出警告，且不会履行动作。因此， Qt::MatchCaseSensitive 标志不起作用。使用 caseSensitivity 特性能控制区分大小写。

默认模式为 Qt::MatchStartsWith .

访问函数：

Qt::MatchFlags	filterMode () const
void	setFilterMode (Qt::MatchFlags filterMode )

另请参阅 caseSensitivity .

maxVisibleItems : int

此特性保持补全器屏幕的最大允许尺寸 (以项为单位度量)

默认情况下，此属性拥有 7 值。

访问函数：

int	maxVisibleItems () const
void	setMaxVisibleItems (int maxItems )

modelSorting : ModelSorting

此特性保持模型排序方式

默认情况下，对提供补全的模型中项的有关次序不做假定。

若模型数据为 completionColumn () 和 completionRole () 将按升序排序，可以把此特性设为 CaseSensitivelySortedModel or CaseInsensitivelySortedModel 。对于大型模型，这可以导致显著性能改进，因为补全器对象可以使用二进制搜索算法，而不是线性搜索算法。

模型的排序次序 (即：升序或降序) 是通过审查模型内容动态确定的。

注意： 上述性能改进不会发生，当补全器 caseSensitivity 不同于模型排序时使用的区分大小写。

访问函数：

QCompleter::ModelSorting	modelSorting () const
void	setModelSorting (QCompleter::ModelSorting sorting )

另请参阅 setCaseSensitivity () 和 QCompleter::ModelSorting .

wrapAround : bool

此特性保持补全环绕，当透过项导航时

默认为 true。

访问函数：

bool	wrapAround () const
void	setWrapAround (bool wrap )

成员函数文档编制

QCompleter:: QCompleter ( QObject * parent = nullptr)

构造补全器对象采用给定 parent .

QCompleter:: QCompleter ( QAbstractItemModel * model , QObject * parent = nullptr)

构造补全器对象采用给定 parent 提供补全来自指定 model .

QCompleter:: QCompleter (const QStringList & list , QObject * parent = nullptr)

构造 QCompleter 对象采用给定 parent 使用指定 list 作为可能的补全源。

`[override virtual noexcept]` 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 () 信号被激发采用当前补全。

int QCompleter:: completionCount () const

返回为当前前缀的补全数。对于具有大量项的未排序模型，这可能是昂贵的。使用 setCurrentRow () 和 currentCompletion () 去遍历所有补全。

QAbstractItemModel *QCompleter:: completionModel () const

返回补全模型。补全模型是包含为当前补全前缀的所有可能匹配的只读列表模型。补全模型被自动更新以反映当前补全。

注意： 此函数的返回值被定义为 QAbstractItemModel 纯粹为通用性。这种实际返回的模型是实例对于 QAbstractProxyModel 子类。

另请参阅 completionPrefix and model ().

QString QCompleter:: currentCompletion () const

返回当前补全字符串。这包括 completionPrefix 。当同时使用 setCurrentRow ()，它可以被用于遍历所有匹配。

另请参阅 setCurrentRow () 和 currentIndex ().

QModelIndex QCompleter:: currentIndex () const

返回当前补全的模型索引在 completionModel ().

另请参阅 setCurrentRow (), currentCompletion ()，和 model ().

int QCompleter:: currentRow () const

返回当前行。

另请参阅 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){ /* ... */ });

QAbstractItemModel *QCompleter:: model () const

返回提供补全字符串的模型。

另请参阅 setModel () 和 completionModel ().

`[虚拟]` QString QCompleter:: pathFromIndex (const QModelIndex & index ) const

返回路径为给定 index 。补全器对象使用此，以从底层模型中获得补全文本。

默认实现返回编辑角色的列表模型项。它返回绝对文件路径，若模型是 QFileSystemModel .

另请参阅 splitPath ().

返回用于显示补全的弹出窗口。

另请参阅 setPopup ().

bool QCompleter:: setCurrentRow ( int row )

把当前行设为 row 指定。返回 true 若成功；否则返回 false .

此函数可以被使用沿着 currentCompletion () 去遍历所有可能的补全。

另请参阅 currentRow (), currentCompletion ()，和 completionCount ().

void QCompleter:: setModel ( QAbstractItemModel * model )

把提供补全的模型设为 model 。 model 可以是列表模型 (或树模型)。若模型事先已经被设置，且它有 QCompleter 作为其父级，它将被删除。

为方便起见，若 model 是 QFileSystemModel , QCompleter 切换其 caseSensitivity to Qt::CaseInsensitive 在 Windows 和 Qt::CaseSensitive 在其它平台。

另请参阅 completionModel (), modelSorting ，和处理树模型 .

void QCompleter:: setPopup ( QAbstractItemView * popup )

把用于显示补全的弹出窗口设为 popup . QCompleter 拥有视图的所有权。

A QListView 被自动创建当 completionMode () 被设为 QCompleter::PopupCompletion or QCompleter::UnfilteredPopupCompletion 。默认弹出窗口显示 completionColumn ().

确保此函数被调用，在视图设置被修改之前。这是必需的，因为视图的特性可能要求在视图上设置模型 (例如：隐藏视图列要求在视图上设置模型)。

另请参阅 popup ().

void QCompleter:: setWidget ( QWidget * widget )

把为其提供补全的小部件设为 widget 。此函数被自动调用当 QCompleter 被设置在 QLineEdit 使用 QLineEdit::setCompleter () 或在 QComboBox 使用 QComboBox::setCompleter ()。小部件需要被明确设置，当为自定义小部件提供补全时。

另请参阅 widget (), setModel ()，和 setPopup ().

`[虚拟]` QStringList QCompleter:: splitPath (const QString & path ) const

分割给定 path 成字符串，用于每级匹配在 model ().

默认实现的 splitPath() 分割文件系统路径基于 QDir::separator () 当 sourceModel() 是 QFileSystemModel .

当用于列表模型时，返回列表中的第一项被用于匹配。

另请参阅 pathFromIndex () 和处理树模型 .

返回补全器对象正为其提供补全的 Widget。

另请参阅 setWidget ().

QCompleter 类

公共类型

特性

公共函数

公共槽

信号

重实现保护函数

详细描述

基本用法

遍历补全

补全模型

处理树模型

成员类型文档编制

enum QCompleter:: CompletionMode

enum QCompleter:: ModelSorting

特性文档编制

caseSensitivity : Qt::CaseSensitivity

completionColumn : int

completionMode : CompletionMode

completionPrefix : QString

completionRole : int

filterMode : Qt::MatchFlags

maxVisibleItems : int

modelSorting : ModelSorting

wrapAround : bool

成员函数文档编制

QCompleter:: QCompleter ( QObject * parent = nullptr)

QCompleter:: QCompleter ( QAbstractItemModel * model , QObject * parent = nullptr)

QCompleter:: QCompleter (const QStringList & list , QObject * parent = nullptr)

[override virtual noexcept] QCompleter:: ~QCompleter ()

[signal] void QCompleter:: activated (const QString & text )

[signal] void QCompleter:: activated (const QModelIndex & index )

[slot] void QCompleter:: complete (const QRect & rect = QRect())

int QCompleter:: completionCount () const

QAbstractItemModel *QCompleter:: completionModel () const

QString QCompleter:: currentCompletion () const

QModelIndex QCompleter:: currentIndex () const

int QCompleter:: currentRow () const

[override virtual protected] bool QCompleter:: event ( QEvent * ev )

[override virtual protected] bool QCompleter:: eventFilter ( QObject * o , QEvent * e )

[signal] void QCompleter:: highlighted (const QString & text )

[signal] void QCompleter:: highlighted (const QModelIndex & index )

QAbstractItemModel *QCompleter:: model () const

[虚拟] QString QCompleter:: pathFromIndex (const QModelIndex & index ) const

QAbstractItemView *QCompleter:: popup () const

bool QCompleter:: setCurrentRow ( int row )

void QCompleter:: setModel ( QAbstractItemModel * model )

void QCompleter:: setPopup ( QAbstractItemView * popup )

void QCompleter:: setWidget ( QWidget * widget )

[虚拟] QStringList QCompleter:: splitPath (const QString & path ) const

QWidget *QCompleter:: widget () const

内容

`[override virtual noexcept]` QCompleter:: ~QCompleter ()

`[signal]` void QCompleter:: activated (const QString & text )

`[signal]` void QCompleter:: activated (const QModelIndex & index )

`[slot]` void QCompleter:: complete (const QRect & rect = QRect())

`[override virtual protected]` bool QCompleter:: event ( QEvent * ev )

`[override virtual protected]` bool QCompleter:: eventFilter ( QObject * o , QEvent * e )

`[signal]` void QCompleter:: highlighted (const QString & text )

`[signal]` void QCompleter:: highlighted (const QModelIndex & index )

`[虚拟]` QString QCompleter:: pathFromIndex (const QModelIndex & index ) const

`[虚拟]` QStringList QCompleter:: splitPath (const QString & path ) const