QCompleter 類

QCompleter 類提供基於項模型的補全。更多...

頭：	#include <QCompleter>
qmake:	QT += widgets
Since:	Qt 4.2
繼承：	QObject

該類在 Qt 4.2 引入。

所有成員列錶，包括繼承成員

公共類型

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 (const QStringList & list , QObject * parent = nullptr)
	QCompleter (QAbstractItemModel * model , QObject * parent = nullptr)
	QCompleter (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 QModelIndex & index )
void	activated (const QString & text )
void	highlighted (const QModelIndex & index )
void	highlighted (const QString & text )

重實現保護函數

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 5.2 引入。

訪問函數：

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

另請參閱 caseSensitivity .

maxVisibleItems : int

此特性保持補全器屏幕的最大允許尺寸 (以項為單位度量)

默認情況下，此屬性擁有 7 值。

該特性在 Qt 4.6 引入。

訪問函數：

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。

該特性在 Qt 4.3 引入。

訪問函數：

bool	wrapAround () const
void	setWrapAround (bool wrap )

成員函數文檔編製

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

構造 QCompleter 對象采用給定 parent 使用指定 list 作為可能的補全源。

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

構造補全器對象采用給定 parent 提供補全來自指定 model .

QCompleter:: QCompleter ( QObject * parent = nullptr)

構造補全器對象采用給定 parent .

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

發送此信號，當項在 popup () 被用戶激活。(通過點擊或按下迴車鍵)。項的 index 在 completionModel () 有給定。

注意： 信號 activated 在此類中被重載。通過使用函數指針句法連接到此信號，Qt 提供用於獲得如此範例展示的函數指針的方便幫助程序：

connect(completer, QOverload<const QModelIndex &>::of(&QCompleter::activated),
    [=](const QModelIndex &index){ /* ... */ });

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

發送此信號，當項在 popup () 被用戶激活 (通過點擊或按下迴車鍵)。項的 text 有給定。

注意： 信號 activated 在此類中被重載。通過使用函數指針句法連接到此信號，Qt 提供用於獲得如此範例展示的函數指針的方便幫助程序：

connect(completer, QOverload<const QString &>::of(&QCompleter::activated),
    [=](const QString &text){ /* ... */ });

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

For QCompleter::PopupCompletion 和 QCompletion::UnfilteredPopupCompletion 模式，調用此函數顯示當前補全的彈齣窗口。默認情況下，若 rect 未指定，彈齣窗口顯示在底部對於 widget ()。若 rect 被指定，彈齣窗口顯示在矩形的左邊緣。

For QCompleter::InlineCompletion 模式， highlighted () 信號被激發采用當前補全。

`[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){ /* ... */ });

`[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){ /* ... */ });

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

銷毀補全器對象。

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).

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 (const QStringList & list , QObject * parent = nullptr)

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

QCompleter:: QCompleter ( QObject * parent = nullptr)

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

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

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

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

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

[override virtual] QCompleter:: ~QCompleter ()

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 )

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

內容

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

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

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

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

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

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

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

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

`[虛擬]` QString QCompleter:: pathFromIndex (const QModelIndex & index ) const

`[虛擬]` QStringList QCompleter:: splitPath (const QString & path ) const