The QCompleter class provides completions based on an item model. More...

Inheritance diagram for QCompleter:

Public Types
enum	CompletionMode

enum	ModelSorting

Public Signals
void	activated (const QModelIndex &index)

void	activated (const QString &text)

void	highlighted (const QModelIndex &index)

void	highlighted (const QString &text)

Public Signals inherited from QObject
void	destroyed (QObject *obj=nullptr)

void	objectNameChanged (const QString &objectName)

Public Slots
void	complete (const QRect &rect=QRect ())

void	setCompletionPrefix (const QString &prefix)

void	setWrapAround (bool wrap)

Public Slots inherited from QObject
void	deleteLater ()

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

	QCompleter (QAbstractItemModel model, QObject parent=nullptr)

	QCompleter (QObject *parent=nullptr)

	~QCompleter ()

Qt::CaseSensitivity	caseSensitivity () const

int	completionColumn () const

int	completionCount () const

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

ModelSorting	modelSorting () const

virtual QString	pathFromIndex (const QModelIndex &index) const

QAbstractItemView *	popup () const

void	setCaseSensitivity (Qt::CaseSensitivity caseSensitivity)

void	setCompletionColumn (int column)

void	setCompletionMode (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 (ModelSorting sorting)

void	setPopup (QAbstractItemView *popup)

void	setWidget (QWidget *widget)

virtual QStringList	splitPath (const QString &path) const

QWidget *	widget () const

bool	wrapAround () const

Public Methods inherited from QObject
	QObject (QObject *parent=nullptr)

	~QObject ()

bool	blockSignals (bool block)

const QList< QObject * > &	children () const

bool	connect (const QObject *sender, const QString &signalMethod, const QString &location, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)

bool	connect (const QObject *sender, const QString &signalMethod, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)

bool	disconnect (const QObject *receiver, const QString &slotMethod=QString ()) const

bool	disconnect (const QString &signalMethod, const QString &location, const QObject *receiver=nullptr, const QString &slotMethod=QString ()) const

bool	disconnect (const QString &signalMethod=QString (), const QObject *receiver=nullptr, const QString &slotMethod=QString ()) const

void	dumpObjectInfo ()

void	dumpObjectTree ()

QList< QString >	dynamicPropertyNames () const

template<typename T >
T	findChild (const QString &childName=QString ()) const

template<class T >
QList< T >	findChildren (const QRegularExpression &regExp, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const

template<class T >
QList< T >	findChildren (const QString &childName=QString (), Qt::FindChildOptions options=Qt::FindChildrenRecursively) const

bool	inherits (const QString &className) const

void	installEventFilter (QObject *filterObj)

bool	isWidgetType () const

bool	isWindowType () const

void	killTimer (int id)

const QMetaObject *	metaObject () const

void	moveToThread (QThread *targetThread)

QString	objectName () const

QObject *	parent () const

template<class T = QVariant>
T	property (const QString &name) const

void	removeEventFilter (QObject *obj)

void	setObjectName (const QString &name)

void	setParent (QObject *parent)

bool	setProperty (const QString &name, const QVariant &value)

bool	signalsBlocked () const

int	startTimer (int interval, Qt::TimerType timerType=Qt::CoarseTimer)

QThread *	thread () const

Protected Methods
bool	event (QEvent *event) override

bool	eventFilter (QObject object, QEvent event) override

Protected Methods inherited from QObject
virtual void	childEvent (QChildEvent *event)

virtual void	connectNotify (const QMetaMethod &signalMethod) const

virtual void	customEvent (QEvent *event)

virtual void	disconnectNotify (const QMetaMethod &signalMethod) const

bool	isSignalConnected (const QMetaMethod &signalMethod) const

int	receivers (const QString &signal) const

QObject *	sender () const

int	senderSignalIndex () const

virtual void	timerEvent (QTimerEvent *event)

Properties
	caseSensitivity

	completionColumn

	completionMode

	completionPrefix

	completionRole

	maxVisibleItems

	modelSorting

	wrapAround

Properties inherited from QObject
	objectName

Additional Inherited Members
Static Public Methods inherited from QObject
static bool	connect (const QObject sender, const QMetaMethod &signalMethod, const QObject receiver, const QMetaMethod &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)

static bool	connect (const QObject sender, const QString &signalMethod, const QObject receiver, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection, const QString &location=QString ())

static bool	connect (const QObject sender, const QString &signalMethod, const QString &location, const QObject receiver, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)

template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
static bool	connect (const Sender sender, void (SignalClass::signalMethod)(SignalArgs...), const Receiver receiver, SlotReturn (SlotClass::slotMethod)(SlotArgs...), Qt::ConnectionType type=Qt::AutoConnection)

template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
static bool	connect (const Sender sender, void (SignalClass::signalMethod)(SignalArgs...), const Receiver *receiver, T slotLambda, Qt::ConnectionType type=Qt::AutoConnection)

static bool	disconnect (const QObject sender, const QMetaMethod &signalMethod, const QObject receiver, const QMetaMethod &slotMethod)

static bool	disconnect (const QObject sender, const QString &signalMethod, const QObject receiver, const QString &slotMethod)

static bool	disconnect (const QObject sender, const QString &signalMethod, const QString &location, const QObject receiver, const QString &slotMethod)

static bool	disconnect (const QObject sender, std::nullptr_t, const QObject receiver, std::nullptr_t)

template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
static bool	disconnect (const Sender sender, void (SignalClass::signalMethod)(SignalArgs...), const Receiver receiver, SlotReturn (SlotClass::slotMethod)(SlotArgs...))

template<class Sender , class SignalClass , class... SignalArgs, class Receiver >
static bool	disconnect (const Sender sender, void (SignalClass::signalMethod)(SignalArgs...), const Receiver *receiver, std::nullptr_t slotMethod=nullptr)

template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
static bool	disconnect (const Sender sender, void (SignalClass::signalMethod)(SignalArgs...), const Receiver *receiver, T slotMethod)

static QMetaObject &	staticMetaObject ()

static QString	tr (const char text, const char comment=nullptr, std::optional< int > numArg=std::optional< int >())

Related Functions inherited from QObject
T	qobject_cast (QObject *object)

	QObjectList

Detailed Description

The QCompleter class provides text completion based on an item model. A QCompleter is often used with a QLineEdit or QComboBox.

When the user starts typing a word QCompleter suggests possible ways of completing the word, based on a given list of words. The word list is provided as a QAbstractItemModel.If the word list is static, it can be passed as a QStringList to the constructor.

Basic Usage

The following example shows how to provide auto completion using a word list in a 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 can be used to provide auto completion of file names.

QCompleter *completer = new QCompleter(this);
completer->setModel(new QDirModel(completer));
lineEdit->setCompleter(completer);

To set the model on which QCompleter should operate, call setModel(). By default, QCompleter will attempt to match the completion prefix (i.e., the word that the user has started typing) against the Qt::EditRole data stored in column 0 in the model case sensitively. This can be changed using setCompletionRole(), setCompletionColumn(), and setCaseSensitivity().

If the model is sorted on the column and role that are used for completion, you can call setModelSorting() with either 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 model can be a list model, a table model, or a tree model. Completion on tree models is slightly more involved and is covered in the Handling Tree Models section.

The completionMode() determines the mode used to provide completions to the user.

Iterating Through Completions

To retrieve the first completion call the method setCompletionPrefix() and then call currentCompletion(). If you want to iterate over the entire set of possible completions, call currentCompletion() in a loop as shown below.

The method completionCount() returns the total number of completions for the current prefix. This method is slow and should be avoided when possible.

for (int i = 0; completer->setCurrentRow(i); i++) {
    qDebug() << completer->currentCompletion() << " is match number " << i;
}

Completion Model

The method 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. Calling setCompletionPrefix() 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.

Consider the example of a user typing in a file system path using the QFileSystemModel. The completion occurs for every element in the path. For example, if the current text is C:\Wind, QCompleter might suggest Windows to complete the current path element. Similarly, if the current text is C:\Windows\Sy, QCompleter might suggest System.

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, it needs to be split as "C:", "Windows" and "Sy". The default implementation of splitPath(), splits the completionPrefix using QDir::separator() if the model is a QFileSystemModel.

To provide completions, QCompleter needs to know the path from an index. This is provided by pathFromIndex(). The default implementation of pathFromIndex(), returns the data for the edit role for list models and the absolute file path if the mode is a QFileSystemModel.

See also: QAbstractItemModel, QLineEdit, QComboBox

Member Enumeration Documentation

enum QCompleter::CompletionMode

This enum specifies how completions are provided to the user.

Constant	Value	Description
`QCompleter::PopupCompletion`	`0`	Current completions are displayed in a popup window.
`QCompleter::InlineCompletion`	`2`	Completions appear inline (as selected text).
`QCompleter::UnfilteredPopupCompletion`	`1`	All possible completions are displayed in a popup window with the most likely suggestion indicated as current.

See also: setCompletionMode()

enum QCompleter::ModelSorting

This enum specifies how the items in the model are sorted.

Constant	Value	Description
`QCompleter::UnsortedModel`	`0`	The model is unsorted.
`QCompleter::CaseSensitivelySortedModel`	`1`	The model is sorted case sensitively.
`QCompleter::CaseInsensitivelySortedModel`	`2`	The model is sorted case insensitively.

See also: setModelSorting()

Constructor & Destructor Documentation

QCompleter::QCompleter ( QObject * parent = nullptr )

Constructs a completer object with the given parent.

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

Constructs a completer object with the given parent that provides completions from the specified model.

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

Constructs a QCompleter object with the given parent that uses the specified list as a source of possible completions.

QCompleter::~QCompleter ( )

Destroys the completer object.

Method Documentation

void QCompleter::activated ( const QModelIndex & index )

signal

This signal is sent when an item in the popup() is activated by the user. (by clicking or pressing return). The item's index in the completionModel() is given.

void QCompleter::activated ( const QString & text )

signal

This signal is sent when an item in the popup() is activated by the user (by clicking or pressing return). The item's text is given.

Qt::CaseSensitivity QCompleter::caseSensitivity ( ) const

Returns the value of the property.

void QCompleter::complete ( const QRect & rect = QRect() )

slot

For QCompleter::PopupCompletion and QCompletion::UnfilteredPopupCompletion modes, calling this function displays the popup displaying the current completions. By default, if rect is not specified, the popup is displayed on the bottom of the widget(). If rect is specified the popup is displayed on the left edge of the rectangle.

For QCompleter::InlineCompletion mode, the highlighted() signal is emitted with the current completion.

int QCompleter::completionColumn ( ) const

Returns the value of the property.

int QCompleter::completionCount ( ) const

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() and currentCompletion() to iterate through all the completions.

CompletionMode QCompleter::completionMode ( ) const

Returns the value of the property.

QAbstractItemModel * QCompleter::completionModel ( ) const

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 an QAbstractProxyModel subclass.

See also: completionPrefix, model()

QString QCompleter::completionPrefix ( ) const

Returns the value of the property.

int QCompleter::completionRole ( ) const

Returns the value of the property.

QString QCompleter::currentCompletion ( ) const

Returns the current completion string. This includes the completionPrefix. When used alongside setCurrentRow(), it can be used to iterate through all the matches.

See also: setCurrentRow(), currentIndex()

QModelIndex QCompleter::currentIndex ( ) const

Returns the model index of the current completion in the completionModel().

See also: setCurrentRow(), currentCompletion(), model()

int QCompleter::currentRow ( ) const

Returns the current row.

See also: setCurrentRow()

bool QCompleter::event ( QEvent * event )

overrideprotectedvirtual

Reimplemented from QObject::event()

bool QCompleter::eventFilter	(	QObject *	object,
		QEvent *	event
	)

overrideprotectedvirtual

Reimplemented from QObject::eventFilter()

Qt::MatchFlags QCompleter::filterMode ( ) const

Returns the value of the property.

void QCompleter::highlighted ( const QModelIndex & index )

signal

This signal is sent when an item in the popup() is highlighted by the user. It is also sent if complete() is called with the completionMode() set to QCompleter::InlineCompletion. The item's index in the completionModel() is given.

void QCompleter::highlighted ( const QString & text )

signal

This signal is sent when an item in the popup() is highlighted by the user. It is also sent if complete() is called with the completionMode() set to QCompleter::InlineCompletion. The item's text is given.

int QCompleter::maxVisibleItems ( ) const

Returns the value of the property.

QAbstractItemModel * QCompleter::model ( ) const

Returns the model that provides completion strings.

See also: setModel(), completionModel()

ModelSorting QCompleter::modelSorting ( ) const

Returns the value of the property.

QString QCompleter::pathFromIndex ( const QModelIndex & index ) const

virtual

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 a QFileSystemModel.

See also: splitPath()

QAbstractItemView * QCompleter::popup ( ) const

Returns the popup used to display completions.

See also: setPopup()

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

Sets the value of the property to caseSensitivity.

void QCompleter::setCompletionColumn ( int column )

Sets the value of the property to column.

void QCompleter::setCompletionMode ( CompletionMode mode )

Sets the value of the property to mode.

void QCompleter::setCompletionPrefix ( const QString & prefix )

slot

Sets the value of the property to prefix.

void QCompleter::setCompletionRole ( int role )

Sets the value of the property to role.

bool QCompleter::setCurrentRow ( int row )

Sets the current row to the row specified. Returns true if successful, otherwise returns false. This method may be used along with currentCompletion() to iterate through all the possible completions.

See also: currentRow(), currentCompletion(), completionCount()

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

Sets the value of the property to filterMode.

void QCompleter::setMaxVisibleItems ( int maxItems )

Sets the value of the property to maxItems.

void QCompleter::setModel ( QAbstractItemModel * model )

Sets the model which provides completions to model. The model can be list model or a tree model. If a model has been already previously set and it has the QCompleter as its parent, it is deleted. If model is a QFileSystemModel, QCompleter switches its caseSensitivity to Qt::CaseInsensitive on Windows and Qt::CaseSensitive on other platforms.

See also: completionModel(), modelSorting, Handling Tree Models

void QCompleter::setModelSorting ( ModelSorting sorting )

Sets the value of the property to sorting.

void QCompleter::setPopup ( QAbstractItemView * popup )

Sets the popup used to display completions to popup. QCompleter takes ownership of the view.

A QListView is automatically created when the completionMode() is set to QCompleter::PopupCompletion or QCompleter::UnfilteredPopupCompletion. The default popup displays the completionColumn().

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: popup()

void QCompleter::setWidget ( QWidget * widget )

Sets the widget for which completion are provided for to widget. This function is automatically called when a QCompleter is set on a QLineEdit using QLineEdit::setCompleter() or on a QComboBox using QComboBox::setCompleter(). The widget needs to be set explicitly when providing completions for custom widgets.

See also: widget(), setModel(), setPopup()

void QCompleter::setWrapAround ( bool wrap )

slot

Sets the value of the property to wrap.

QStringList QCompleter::splitPath ( const QString & path ) const

virtual

Splits the given path into strings that are used to match at each level in the model(). The default implementation of splitPath() splits a file system path based on QDir::separator() when the sourceModel() is a QFileSystemModel. When used with list models, the first item in the returned list is used for matching.

See also: pathFromIndex(), Handling Tree Models

QWidget * QCompleter::widget ( ) const

Returns the widget for which the completer object is providing completions.

See also: setWidget()

bool QCompleter::wrapAround ( ) const

Returns the value of the property.

Property Documentation

QCompleter::caseSensitivity

This property holds the case sensitivity of the matching.

The default is Qt::CaseSensitive.

See also: completionColumn, completionRole, modelSorting

Properties	Class Methods
read	caseSensitivity
write	setCaseSensitivity

QCompleter::completionColumn

This property holds the column in the model in which completions are searched for.

If the popup() is a QListView, it is automatically setup to display this column.

By default, the match column is 0.

See also: completionRole, caseSensitivity

Properties	Class Methods
read	completionColumn
write	setCompletionColumn

QCompleter::completionMode

This property holds how the completions are provided to the user.

The default value is QCompleter::PopupCompletion.

Properties	Class Methods
read	completionMode
write	setCompletionMode

QCompleter::completionPrefix

This property holds the completion prefix used to provide completions.

The completionModel() is updated to reflect the list of possible matches for prefix.

Properties	Class Methods
read	completionPrefix
write	setCompletionPrefix

QCompleter::completionRole

This property holds the item role to be used to query the contents of items for matching.

The default role is Qt::EditRole.

See also: completionColumn, caseSensitivity

Properties	Class Methods
read	completionRole
write	setCompletionRole

QCompleter::maxVisibleItems

This property holds the maximum allowed size on screen of the completer, measured in items.

By default, this property has a value of 7.

Properties	Class Methods
read	maxVisibleItems
write	setMaxVisibleItems

QCompleter::modelSorting

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() and 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 of the model is determined dynamically by inspecting the contents of the model.

The performance improvements described above can not take place when the completer's caseSensitivity is different to the case sensitivity used by the model's when sorting.

See also: setCaseSensitivity(), QCompleter::ModelSorting

Properties	Class Methods
read	modelSorting
write	setModelSorting

QCompleter::wrapAround

This property holds the completions wrap around when navigating through items.

The default is true.

Properties	Class Methods
read	wrapAround
write	setWrapAround

Public Types

Public Signals

Public Slots

Public Methods

Protected Methods

Properties

Additional Inherited Members

Detailed Description

Basic Usage

Iterating Through Completions

Completion Model

Handling Tree Models

Member Enumeration Documentation

Constructor & Destructor Documentation

Method Documentation

Property Documentation