就業培訓     下載中心     Wiki     聯絡
登錄   注冊
  1. 首頁
  2. Qt 5.12.12
  3. Qt Widgets
  4. C++ 類
  5. QCompleter

內容

QCompleter 類

The QCompleter class provides completions based on an item model. 更多...

頭： #include <QCompleter>
qmake: QT += widgets
Since: Qt 4.2
繼承： 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 )

靜態公共成員

const QMetaObject staticMetaObject

重實現保護函數

virtual bool event (QEvent * ev ) override
virtual bool eventFilter (QObject * o , QEvent * e ) override

詳細描述

The QCompleter class provides completions based on an item model.

可以使用 QCompleter to provide auto completions in any Qt widget, such as QLineEdit and QComboBox . 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 a QAbstractItemModel (對於是靜態單詞列錶的簡單應用程序，可以傳遞 QStringList to QCompleter 's constructor.)

基本用法

A QCompleter is used typically with a 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);

To set the model on which QCompleter should operate, call setModel ()。默認情況下， QCompleter will attempt to match the 補全前綴 (即：用戶已開始鍵入的單詞) 針對 Qt::EditRole 區分大小寫的模型數據存儲第 0 列。這可以改變使用 setCompletionRole (), setCompletionColumn ()，和 setCaseSensitivity ().

若用於補全的模型按列和角色排序，可以調用 setModelSorting () 采用 QCompleter::CaseSensitivelySortedModel or QCompleter::CaseInsensitivelySortedModel as the argument. On large models, this can lead to significant performance improvements, because QCompleter can then use binary search instead of linear search. The binary search only works when the 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 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.

讓我們以用戶鍵入文件係統路徑為例。模型是 (分層) QFileSystemModel 。補全齣現為每路徑元素。例如，若當前文本是 C:\Wind , QCompleter might suggest Windows 去補全當前路徑元素。同樣，若當前文本是 C:\Windows\Sy , QCompleter might suggest 係統 .

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. For C:\Windows\Sy ，它需要被分割成 C: Windows 及 Sy。默認實現的 splitPath ()，分割 completionPrefix 使用 QDir::separator () 若模型是 QFileSystemModel .

To provide completions, QCompleter needs to know the path from an index. This is provided by 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 .

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 是以鍵入字符結尾的那些。

Currently, only these three modes are implemented. Setting filterMode to any other Qt::MatchFlag will issue a warning, and no action will be performed.

默認模式為 Qt::MatchStartsWith .

該特性在 Qt 5.2 引入。

訪問函數：

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

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

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

重實現自 QObject::eventFilter ().

[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 () 和 處理樹模型 .

QWidget *QCompleter:: widget () const

返迴補全器對象正為其提供補全的 Widget。

另請參閱 setWidget ().