CopperSpice API  1.7.2
QCompleter Class Reference

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

Inheritance diagram for QCompleter:
QObject

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
 
QAbstractItemModelcompletionModel () const
 
QString completionPrefix () const
 
int completionRole () const
 
QString currentCompletion () const
 
QModelIndex currentIndex () const
 
int currentRow () const
 
Qt::MatchFlags filterMode () const
 
int maxVisibleItems () const
 
QAbstractItemModelmodel () const
 
ModelSorting modelSorting () const
 
virtual QString pathFromIndex (const QModelIndex &index) const
 
QAbstractItemViewpopup () 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
 
QWidgetwidget () 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< QStringdynamicPropertyNames () const
 
template<typename 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 &objName=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 QMetaObjectmetaObject () const
 
void moveToThread (QThread *targetThread)
 
QString objectName () const
 
QObject * parent () const
 
template<class T = QVariant>
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)
 
QThreadthread () 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)
 
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 QMetaObjectstaticMetaObject ()
 
static QString tr (const char *text, const char *comment=nullptr, std::optional< int > numArg=std::optional< int >())
 

Detailed Description

The QCompleter class provides completions based on an item model.

You can use QCompleter to provide auto completions in any CopperSpice 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. (For simple applications, where the word list is static, you can pass a QStringList to QCompleter's constructor.)

Basic Usage

A QCompleter is used typically with a QLineEdit or QComboBox. For example, here's how to provide auto completions from a simple 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. For example:

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 a single candidate string, call setCompletionPrefix() with the text that needs to be completed and call currentCompletion(). You can iterate through the list of completions as below:

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

completionCount() returns the total number of completions for the current prefix. completionCount() should be avoided when possible, since it requires a scan of the entire model.

The Completion Model

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.

Let's take the example of a user typing in a file system path. The model is a (hierarchical) 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

This enum specifies how completions are provided to the user.

ConstantValueDescription
QCompleter::PopupCompletion0Current completions are displayed in a popup window.
QCompleter::InlineCompletion2Completions appear inline (as selected text).
QCompleter::UnfilteredPopupCompletion1All possible completions are displayed in a popup window with the most likely suggestion indicated as current.
See also
setCompletionMode()

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

ConstantValueDescription
QCompleter::UnsortedModel0The model is unsorted.
QCompleter::CaseSensitivelySortedModel1The model is sorted case sensitively.
QCompleter::CaseInsensitivelySortedModel2The 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

Documentation pending.

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

Documentation pending.

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

Documentation pending.

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

Documentation pending.

int QCompleter::completionRole ( ) const

Documentation pending.

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

Reimplemented from QObject.

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

Reimplemented from QObject::eventFilter().

Reimplemented from QObject.

Qt::MatchFlags QCompleter::filterMode ( ) const

Documentation pending.

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

Documentation pending.

QAbstractItemModel * QCompleter::model ( ) const

Returns the model that provides completion strings.

See also
setModel(), completionModel()
ModelSorting QCompleter::modelSorting ( ) const

Documentation pending.

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)

Documentation pending.

void QCompleter::setCompletionColumn ( int  column)

Documentation pending.

void QCompleter::setCompletionMode ( CompletionMode  mode)

Documentation pending.

void QCompleter::setCompletionPrefix ( const QString prefix)
slot

Documentation pending.

void QCompleter::setCompletionRole ( int  role)

Documentation pending.

bool QCompleter::setCurrentRow ( int  row)

Sets the current row to the row specified. Returns true if successful, otherwise returns false.

This function may be used along with currentCompletion() to iterate through all the possible completions.

See also
currentRow(), currentCompletion(), completionCount()
void QCompleter::setFilterMode ( Qt::MatchFlags  filterMode)

Documentation pending.

void QCompleter::setMaxVisibleItems ( int  maxItems)

Documentation pending.

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.

For convenience, 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)

Documentation pending.

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

Documentation pending.

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

Documentation pending.

Property Documentation

QCompleter::caseSensitivity

This property holds the case sensitivity of the matching.

The default is Qt::CaseSensitive.

See also
completionColumn, completionRole, modelSorting
PropertiesClass 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
PropertiesClass Methods
read completionColumn
write setCompletionColumn
QCompleter::completionMode

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

The default value is QCompleter::PopupCompletion.

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

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

PropertiesClass 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 (i.e ascending or descending order) of the model is determined dynamically by inspecting the contents of the model.

Note
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
PropertiesClass Methods
read modelSorting
write setModelSorting
QCompleter::wrapAround

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

The default is true.

PropertiesClass Methods
read wrapAround
write setWrapAround