QCompleter Class Reference

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

#include <qcompleter.h>

Inheritance diagram for QCompleter:

Public Types
enum	CompletionMode { PopupCompletion, UnfilteredPopupCompletion, InlineCompletion }
	This enum specifies how completions are provided to the user. More...
enum	ModelSorting { UnsortedModel = 0, CaseSensitivelySortedModel, CaseInsensitivelySortedModel }
	This enum specifies how the items in the model are sorted. More...

Public Slots
void	complete (const QRect &rect=QRect())
	For QCompleter::PopupCompletion and QCompletion::UnfilteredPopupCompletion modes, calling this function displays the popup displaying the current completions. More...
void	setCompletionPrefix (const QString &prefix)
void	setWrapAround (bool wrap)
Public Slots inherited from QObject
void	deleteLater ()
	Schedules this object for deletion. More...

Signals
void	activated (const QString &text)
	This signal is sent when an item in the popup() is activated by the user (by clicking or pressing return). More...
void	activated (const QModelIndex &index)
	This signal is sent when an item in the popup() is activated by the user. More...
void	highlighted (const QString &text)
	This signal is sent when an item in the popup() is highlighted by the user. More...
void	highlighted (const QModelIndex &index)
	This signal is sent when an item in the popup() is highlighted by the user. More...
Signals inherited from QObject
void	destroyed (QObject *=0)
	This signal is emitted immediately before the object obj is destroyed, and can not be blocked. More...

Public Functions
Qt::CaseSensitivity	caseSensitivity () const
int	completionColumn () const
int	completionCount () const
	Returns the number of completions for the current prefix. More...
CompletionMode	completionMode () const
QAbstractItemModel *	completionModel () const
	Returns the completion model. More...
QString	completionPrefix () const
int	completionRole () const
QString	currentCompletion () const
	Returns the current completion string. More...
QModelIndex	currentIndex () const
	Returns the model index of the current completion in the completionModel(). More...
int	currentRow () const
	Returns the current row. More...
int	maxVisibleItems () const
QAbstractItemModel *	model () const
	Returns the model that provides completion strings. More...
ModelSorting	modelSorting () const
virtual QString	pathFromIndex (const QModelIndex &index) const
	Returns the path for the given index. More...
QAbstractItemView *	popup () const
	Returns the popup used to display completions. More...
	QCompleter (QObject *parent=0)
	Constructs a completer object with the given parent. More...
	QCompleter (QAbstractItemModel *model, QObject *parent=0)
	Constructs a completer object with the given parent that provides completions from the specified model. More...
	QCompleter (const QStringList &completions, QObject *parent=0)
	Constructs a QCompleter object with the given parent that uses the specified list as a source of possible completions. More...
void	setCaseSensitivity (Qt::CaseSensitivity caseSensitivity)
void	setCompletionColumn (int column)
void	setCompletionMode (CompletionMode mode)
void	setCompletionRole (int role)
bool	setCurrentRow (int row)
	Sets the current row to the row specified. More...
void	setMaxVisibleItems (int maxItems)
void	setModel (QAbstractItemModel *c)
	Sets the model which provides completions to model. More...
void	setModelSorting (ModelSorting sorting)
void	setPopup (QAbstractItemView *popup)
	Sets the popup used to display completions to popup. More...
void	setWidget (QWidget *widget)
	Sets the widget for which completion are provided for to widget. More...
virtual QStringList	splitPath (const QString &path) const
	Splits the given path into strings that are used to match at each level in the model(). More...
QWidget *	widget () const
	Returns the widget for which the completer object is providing completions. More...
bool	wrapAround () const
	~QCompleter ()
	Destroys the completer object. More...
Public Functions inherited from QObject
bool	blockSignals (bool b)
	If block is true, signals emitted by this object are blocked (i.e., emitting a signal will not invoke anything connected to it). More...
const QObjectList &	children () const
	Returns a list of child objects. More...
bool	connect (const QObject *sender, const char *signal, const char *member, Qt::ConnectionType type=Qt::AutoConnection) const
bool	disconnect (const char *signal=0, const QObject *receiver=0, const char *member=0)
bool	disconnect (const QObject *receiver, const char *member=0)
void	dumpObjectInfo ()
	Dumps information about signal connections, etc. More...
void	dumpObjectTree ()
	Dumps a tree of children to the debug output. More...
QList< QByteArray >	dynamicPropertyNames () const
	Returns the names of all properties that were dynamically added to the object using setProperty(). More...
template<typename T >
T	findChild (const QString &aName=QString()) const
	Returns the child of this object that can be cast into type T and that is called name, or 0 if there is no such object. More...
template<typename T >
QList< T >	findChildren (const QString &aName=QString()) const
	Returns all children of this object with the given name that can be cast to type T, or an empty list if there are no such objects. More...
template<typename T >
QList< T >	findChildren (const QRegExp &re) const
bool	inherits (const char *classname) const
	Returns true if this object is an instance of a class that inherits className or a QObject subclass that inherits className; otherwise returns false. More...
void	installEventFilter (QObject *)
	Installs an event filter filterObj on this object. More...
bool	isWidgetType () const
	Returns true if the object is a widget; otherwise returns false. More...
void	killTimer (int id)
	Kills the timer with timer identifier, id. More...
virtual const QMetaObject *	metaObject () const
	Returns a pointer to the meta-object of this object. More...
void	moveToThread (QThread *thread)
	Changes the thread affinity for this object and its children. More...
QString	objectName () const
QObject *	parent () const
	Returns a pointer to the parent object. More...
QVariant	property (const char *name) const
	Returns the value of the object's name property. More...
Q_INVOKABLE	QObject (QObject *parent=0)
	Constructs an object with parent object parent. More...
void	removeEventFilter (QObject *)
	Removes an event filter object obj from this object. More...
void	setObjectName (const QString &name)
void	setParent (QObject *)
	Makes the object a child of parent. More...
bool	setProperty (const char *name, const QVariant &value)
	Sets the value of the object's name property to value. More...
void	setUserData (uint id, QObjectUserData *data)
bool	signalsBlocked () const
	Returns true if signals are blocked; otherwise returns false. More...
int	startTimer (int interval)
	Starts a timer and returns a timer identifier, or returns zero if it could not start a timer. More...
QThread *	thread () const
	Returns the thread in which the object lives. More...
QObjectUserData *	userData (uint id) const
virtual	~QObject ()
	Destroys the object, deleting all its child objects. More...

Protected Functions
bool	event (QEvent *)
	Reimplemented Function More...
bool	eventFilter (QObject *o, QEvent *e)
	Reimplemented Function More...
Protected Functions inherited from QObject
virtual void	childEvent (QChildEvent *)
	This event handler can be reimplemented in a subclass to receive child events. More...
virtual void	connectNotify (const char *signal)
	This virtual function is called when something has been connected to signal in this object. More...
virtual void	customEvent (QEvent *)
	This event handler can be reimplemented in a subclass to receive custom events. More...
virtual void	disconnectNotify (const char *signal)
	This virtual function is called when something has been disconnected from signal in this object. More...
	QObject (QObjectPrivate &dd, QObject *parent=0)
int	receivers (const char *signal) const
	Returns the number of receivers connected to the signal. More...
QObject *	sender () const
	Returns a pointer to the object that sent the signal, if called in a slot activated by a signal; otherwise it returns 0. More...
int	senderSignalIndex () const
virtual void	timerEvent (QTimerEvent *)
	This event handler can be reimplemented in a subclass to receive timer events for the object. More...

Properties
Qt::CaseSensitivity	caseSensitivity
	the case sensitivity of the matching More...
int	completionColumn
	the column in the model in which completions are searched for. More...
CompletionMode	completionMode
	how the completions are provided to the user More...
QString	completionPrefix
	the completion prefix used to provide completions. More...
int	completionRole
	the item role to be used to query the contents of items for matching. More...
int	maxVisibleItems
	the maximum allowed size on screen of the completer, measured in items More...
ModelSorting	modelSorting
	the way the model is sorted More...
bool	wrapAround
	the completions wrap around when navigating through items More...

Additional Inherited Members
Static Public Functions inherited from QObject
static bool	connect (const QObject *sender, const char *signal, const QObject *receiver, const char *member, Qt::ConnectionType=Qt::AutoConnection)
	Creates a connection of the given type from the signal in the sender object to the method in the receiver object. More...
static bool	connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type=Qt::AutoConnection)
static bool	disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *member)
	Disconnects signal in object sender from method in object receiver. More...
static bool	disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &member)
static uint	registerUserData ()
static QString	tr (const char *sourceText, const char *comment=0, int n=-1)
static QString	trUtf8 (const char *sourceText, const char *comment=0, int n=-1)
Static Public Variables inherited from QObject
static const QMetaObject	staticMetaObject
	This variable stores the meta-object for the class. More...
Protected Variables inherited from QObject
QScopedPointer< QObjectData >	d_ptr
Static Protected Variables inherited from QObject
static const QMetaObject	staticQtMetaObject
Related Functions inherited from QObject
T	qFindChildqFindChildren (const QObject *obj, const QString &name)()
QList< T >	qFindChildrenqFindChildren (const QObject *obj, const QString &name)()
QList< T >	qFindChildrenqFindChildren (const QObject *obj, const QRegExp &regExp)()
T *	qobject_cast (QObject *object)
	QObjectList
void *	qt_find_obj_child (QObject *parent, const char *type, const QString &name)
	Returns a pointer to the object named name that inherits type and with a given parent. More...

Detailed Description

The QCompleter class provides completions based on an item model.

Since

4.2

You can use 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. (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 completionPrefix {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 below.

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, {Completer Example}

Definition at line 64 of file qcompleter.h.

Enumerations

CompletionMode

enum QCompleter::CompletionMode

This enum specifies how completions are provided to the user.

• PopupCompletion Current completions are displayed in a popup window.
• InlineCompletion Completions appear inline (as selected text).
• UnfilteredPopupCompletion All possible completions are displayed in a popup window with the most likely suggestion indicated as current.

See also

setCompletionMode()

Enumerator
PopupCompletion
UnfilteredPopupCompletion
InlineCompletion

Definition at line 77 of file qcompleter.h.

                        {
        PopupCompletion,
        UnfilteredPopupCompletion,
        InlineCompletion
    };

ModelSorting

enum QCompleter::ModelSorting

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

• UnsortedModel The model is unsorted.
• CaseSensitivelySortedModel The model is sorted case sensitively.
• CaseInsensitivelySortedModel The model is sorted case insensitively.

See also

setModelSorting()

Enumerator
UnsortedModel
CaseSensitivelySortedModel
CaseInsensitivelySortedModel

Definition at line 83 of file qcompleter.h.

                      {
        UnsortedModel = 0,
        CaseSensitivelySortedModel,
        CaseInsensitivelySortedModel
    };

Constructors and Destructors

QCompleter() [1/3]

QCompleter::QCompleter

(

QObject *

parent = 0

)

Constructs a completer object with the given parent.

Definition at line 942 of file qcompleter.cpp.

: QObject(*new QCompleterPrivate(), parent)
{
    Q_D(QCompleter);
    d->init();
}

QCompleter() [2/3]

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

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

Definition at line 953 of file qcompleter.cpp.

    : QObject(*new QCompleterPrivate(), parent)
{
    Q_D(QCompleter);
    d->init(model);
}

QCompleter() [3/3]

QCompleter::QCompleter	(	const QStringList &	completions,
		QObject *	parent = 0
	)

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

Definition at line 965 of file qcompleter.cpp.

: QObject(*new QCompleterPrivate(), parent)
{
    Q_D(QCompleter);
    d->init(new QStringListModel(list, this));
}

~QCompleter()

QCompleter::~QCompleter

(

)

Destroys the completer object.

Definition at line 976 of file qcompleter.cpp.

{
}

Functions

activated [1/2]

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.

Referenced by setPopup().

activated [2/2]

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.

caseSensitivity()

Qt::CaseSensitivity QCompleter::caseSensitivity

(

)

const

Referenced by setCaseSensitivity().

complete

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 fired with the current completion.

Definition at line 1391 of file qcompleter.cpp.

Referenced by QLineControl::complete().

{
    Q_D(QCompleter);
    QModelIndex idx = d->proxy->currentIndex(false);
    d->hiddenBecauseNoMatch = false;
    if (d->mode == QCompleter::InlineCompletion) {
        if (idx.isValid())
            d->_q_complete(idx, true);
        return;
    }

    Q_ASSERT(d->widget != 0);
    if ((d->mode == QCompleter::PopupCompletion && !idx.isValid())
        || (d->mode == QCompleter::UnfilteredPopupCompletion && d->proxy->rowCount() == 0)) {
        if (d->popup)
            d->popup->hide(); // no suggestion, hide
        d->hiddenBecauseNoMatch = true;
        return;
    }

    popup();
    if (d->mode == QCompleter::UnfilteredPopupCompletion)
        d->setCurrentIndex(idx, false);

    d->showPopup(rect);
    d->popupRect = rect;
}

completionColumn()

int QCompleter::completionColumn

(

)

const

Referenced by setCompletionColumn().

completionCount()

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.

Definition at line 1450 of file qcompleter.cpp.

Referenced by QLineControl::advanceToEnabledItem().

{
    Q_D(const QCompleter);
    return d->proxy->completionCount();
}

completionMode()

CompletionMode QCompleter::completionMode

(

)

const

Referenced by popup(), and setCompletionMode().

completionModel()

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

Definition at line 1707 of file qcompleter.cpp.

Referenced by QLineControl::advanceToEnabledItem().

{
    Q_D(const QCompleter);
    return d->proxy;
}

completionPrefix()

QString QCompleter::completionPrefix

(

)

const

Referenced by setCompletionPrefix(), and splitPath().

completionRole()

int QCompleter::completionRole

(

)

const

Referenced by setCompletionRole().

currentCompletion()

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

Definition at line 1690 of file qcompleter.cpp.

Referenced by QLineControl::complete(), and QLineControl::processKeyEvent().

{
    Q_D(const QCompleter);
    return pathFromIndex(d->proxy->currentIndex(true));
}

currentIndex()

QModelIndex QCompleter::currentIndex

(

)

const

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

See also

setCurrentRow(), currentCompletion(), model()

Definition at line 1677 of file qcompleter.cpp.

Referenced by QLineControl::advanceToEnabledItem().

{
    Q_D(const QCompleter);
    return d->proxy->currentIndex(false);
}

currentRow()

int QCompleter::currentRow

(

)

const

Returns the current row.

See also

setCurrentRow()

Definition at line 1439 of file qcompleter.cpp.

Referenced by QLineControl::advanceToEnabledItem().

{
    Q_D(const QCompleter);
    return d->proxy->currentRow();
}

event()

bool QCompleter::event ( QEvent *  ev )

protectedvirtual

Reimplemented Function

Reimplemented from QObject.

Definition at line 1203 of file qcompleter.cpp.

Referenced by eventFilter().

{
    return QObject::event(ev);
}

eventFilter()

bool QCompleter::eventFilter ( QObject *  o, QEvent *  e  )

protectedvirtual

Reimplemented Function

Reimplemented from QObject.

Definition at line 1211 of file qcompleter.cpp.

{
    Q_D(QCompleter);

    if (d->eatFocusOut && o == d->widget && e->type() == QEvent::FocusOut) {
        d->hiddenBecauseNoMatch = false;
        if (d->popup && d->popup->isVisible())
            return true;
    }

    if (o != d->popup)
        return QObject::eventFilter(o, e);

    switch (e->type()) {
    case QEvent::KeyPress: {
        QKeyEvent *ke = static_cast<QKeyEvent *>(e);

        QModelIndex curIndex = d->popup->currentIndex();
        QModelIndexList selList = d->popup->selectionModel()->selectedIndexes();

        const int key = ke->key();
        // In UnFilteredPopup mode, select the current item
        if ((key == Qt::Key_Up || key == Qt::Key_Down) && selList.isEmpty() && curIndex.isValid()
            && d->mode == QCompleter::UnfilteredPopupCompletion) {
              d->setCurrentIndex(curIndex);
              return true;
        }

        // Handle popup navigation keys. These are hardcoded because up/down might make the
        // widget do something else (lineedit cursor moves to home/end on mac, for instance)
        switch (key) {
        case Qt::Key_End:
        case Qt::Key_Home:
            if (ke->modifiers() & Qt::ControlModifier)
                return false;
            break;

        case Qt::Key_Up:
            if (!curIndex.isValid()) {
                int rowCount = d->proxy->rowCount();
                QModelIndex lastIndex = d->proxy->index(rowCount - 1, d->column);
                d->setCurrentIndex(lastIndex);
                return true;
            } else if (curIndex.row() == 0) {
                if (d->wrap)
                    d->setCurrentIndex(QModelIndex());
                return true;
            }
            return false;

        case Qt::Key_Down:
            if (!curIndex.isValid()) {
                QModelIndex firstIndex = d->proxy->index(0, d->column);
                d->setCurrentIndex(firstIndex);
                return true;
            } else if (curIndex.row() == d->proxy->rowCount() - 1) {
                if (d->wrap)
                    d->setCurrentIndex(QModelIndex());
                return true;
            }
            return false;

        case Qt::Key_PageUp:
        case Qt::Key_PageDown:
            return false;
        }

        // Send the event to the widget. If the widget accepted the event, do nothing
        // If the widget did not accept the event, provide a default implementation
        d->eatFocusOut = false;
        (static_cast<QObject *>(d->widget))->event(ke);
        d->eatFocusOut = true;
        if (!d->widget || e->isAccepted() || !d->popup->isVisible()) {
            // widget lost focus, hide the popup
            if (d->widget && (!d->widget->hasFocus()
#ifdef QT_KEYPAD_NAVIGATION
                || (QApplication::keypadNavigationEnabled() && !d->widget->hasEditFocus())
#endif
                ))
                d->popup->hide();
            if (e->isAccepted())
                return true;
        }

        // default implementation for keys not handled by the widget when popup is open
        switch (key) {
#ifdef QT_KEYPAD_NAVIGATION
        case Qt::Key_Select:
            if (!QApplication::keypadNavigationEnabled())
                break;
#endif
        case Qt::Key_Return:
        case Qt::Key_Enter:
        case Qt::Key_Tab:
            d->popup->hide();
            if (curIndex.isValid())
                d->_q_complete(curIndex);
            break;

        case Qt::Key_F4:
            if (ke->modifiers() & Qt::AltModifier)
                d->popup->hide();
            break;

        case Qt::Key_Backtab:
        case Qt::Key_Escape:
            d->popup->hide();
            break;

        default:
            break;
        }

        return true;
    }

#ifdef QT_KEYPAD_NAVIGATION
    case QEvent::KeyRelease: {
        QKeyEvent *ke = static_cast<QKeyEvent *>(e);
        if (QApplication::keypadNavigationEnabled() && ke->key() == Qt::Key_Back) {
            // Send the event to the 'widget'. This is what we did for KeyPress, so we need
            // to do the same for KeyRelease, in case the widget's KeyPress event set
            // up something (such as a timer) that is relying on also receiving the
            // key release. I see this as a bug in Qt, and should really set it up for all
            // the affected keys. However, it is difficult to tell how this will affect
            // existing code, and I can't test for every combination!
            d->eatFocusOut = false;
            static_cast<QObject *>(d->widget)->event(ke);
            d->eatFocusOut = true;
        }
        break;
    }
#endif

    case QEvent::MouseButtonPress: {
#ifdef QT_KEYPAD_NAVIGATION
        if (QApplication::keypadNavigationEnabled()) {
            // if we've clicked in the widget (or its descendant), let it handle the click
            QWidget *source = qobject_cast<QWidget *>(o);
            if (source) {
                QPoint pos = source->mapToGlobal((static_cast<QMouseEvent *>(e))->pos());
                QWidget *target = QApplication::widgetAt(pos);
                if (target && (d->widget->isAncestorOf(target) ||
                    target == d->widget)) {
                    d->eatFocusOut = false;
                    static_cast<QObject *>(target)->event(e);
                    d->eatFocusOut = true;
                    return true;
                }
            }
        }
#endif
        if (!d->popup->underMouse()) {
            d->popup->hide();
            return true;
        }
        }
        return false;

    case QEvent::InputMethod:
    case QEvent::ShortcutOverride:
        QApplication::sendEvent(d->widget, e);
        break;

    default:
        return false;
    }
    return false;
}

highlighted [1/2]

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.

highlighted [2/2]

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.

maxVisibleItems()

int QCompleter::maxVisibleItems

(

)

const

Referenced by setWrapAround().

model()

QAbstractItemModel * QCompleter::model

(

)

const

Returns the model that provides completion strings.

See also

completionModel()

Definition at line 1062 of file qcompleter.cpp.

Referenced by setModel().

{
    Q_D(const QCompleter);
    return d->proxy->sourceModel();
}

modelSorting()

ModelSorting QCompleter::modelSorting

(

)

const

Referenced by setModelSorting().

pathFromIndex()

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

Reimplemented in QFSCompleter.

Definition at line 1724 of file qcompleter.cpp.

Referenced by currentCompletion().

{
    Q_D(const QCompleter);
    if (!index.isValid())
        return QString();

    QAbstractItemModel *sourceModel = d->proxy->sourceModel();
    if (!sourceModel)
        return QString();
    bool isDirModel = false;
    bool isFsModel = false;
#ifndef QT_NO_DIRMODEL
    isDirModel = qobject_cast<QDirModel *>(d->proxy->sourceModel()) != 0;
#endif
#ifndef QT_NO_FILESYSTEMMODEL
    isFsModel = qobject_cast<QFileSystemModel *>(d->proxy->sourceModel()) != 0;
#endif
    if (!isDirModel && !isFsModel)
        return sourceModel->data(index, d->role).toString();

    QModelIndex idx = index;
    QStringList list;
    do {
        QString t;
        if (isDirModel)
            t = sourceModel->data(idx, Qt::EditRole).toString();
#ifndef QT_NO_FILESYSTEMMODEL
        else
            t = sourceModel->data(idx, QFileSystemModel::FileNameRole).toString();
#endif
        list.prepend(t);
        QModelIndex parent = idx.parent();
        idx = parent.sibling(parent.row(), index.column());
    } while (idx.isValid());

#if (!defined(Q_OS_WIN) || defined(Q_OS_WINCE)) && !defined(Q_OS_SYMBIAN)
    if (list.count() == 1) // only the separator or some other text
        return list[0];
    list[0].clear() ; // the join below will provide the separator
#endif

    return list.join(QDir::separator());
}

popup()

QAbstractItemView * QCompleter::popup

(

)

const

Returns the popup used to display completions.

See also

setPopup()

Definition at line 1182 of file qcompleter.cpp.

Referenced by complete(), QLineControl::complete(), QLineControl::processKeyEvent(), and setPopup().

{
    Q_D(const QCompleter);
#ifndef QT_NO_LISTVIEW
    if (!d->popup && completionMode() != QCompleter::InlineCompletion) {
        QListView *listView = new QListView;
        listView->setEditTriggers(QAbstractItemView::NoEditTriggers);
        listView->setHorizontalScrollBarPolicy(Qt::ScrollBarAlwaysOff);
        listView->setSelectionBehavior(QAbstractItemView::SelectRows);
        listView->setSelectionMode(QAbstractItemView::SingleSelection);
        listView->setModelColumn(d->column);
        QCompleter *that = const_cast<QCompleter*>(this);
        that->setPopup(listView);
    }
#endif // QT_NO_LISTVIEW
    return d->popup;
}

setCaseSensitivity()

void QCompleter::setCaseSensitivity

(

Qt::CaseSensitivity

caseSensitivity

)

Definition at line 1633 of file qcompleter.cpp.

Referenced by QFSCompleter::QFSCompleter(), and setModel().

{
    Q_D(QCompleter);
    if (d->cs == cs)
        return;
    d->cs = cs;
    d->proxy->createEngine();
    d->proxy->invalidate();
}

setCompletionColumn()

void QCompleter::setCompletionColumn

(

int

column

)

Definition at line 1526 of file qcompleter.cpp.

{
    Q_D(QCompleter);
    if (d->column == column)
        return;
#ifndef QT_NO_LISTVIEW
    if (QListView *listView = qobject_cast<QListView *>(d->popup))
        listView->setModelColumn(column);
#endif
    d->column = column;
    d->proxy->invalidate();
}

setCompletionMode()

void QCompleter::setCompletionMode

(

QCompleter::CompletionMode

mode

)

Definition at line 1092 of file qcompleter.cpp.

{
    Q_D(QCompleter);
    d->mode = mode;
    d->proxy->setFiltered(mode != QCompleter::UnfilteredPopupCompletion);

    if (mode == QCompleter::InlineCompletion) {
        if (d->widget)
            d->widget->removeEventFilter(this);
        if (d->popup) {
            d->popup->deleteLater();
            d->popup = 0;
        }
    } else {
        if (d->widget)
            d->widget->installEventFilter(this);
    }
}

setCompletionPrefix

void QCompleter::setCompletionPrefix ( const QString &  prefix )

slot

Definition at line 1659 of file qcompleter.cpp.

Referenced by QLineControl::complete().

{
    Q_D(QCompleter);
    d->prefix = prefix;
    d->proxy->filter(splitPath(prefix));
}

setCompletionRole()

void QCompleter::setCompletionRole

(

int

role

)

Definition at line 1556 of file qcompleter.cpp.

Referenced by setModel(), and QScriptBreakpointsWidget::setScriptsModel().

{
    Q_D(QCompleter);
    if (d->role == role)
        return;
    d->role = role;
    d->proxy->invalidate();
}

setCurrentRow()

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

currentCompletion(), completionCount()

Definition at line 1428 of file qcompleter.cpp.

Referenced by QLineControl::advanceToEnabledItem().

{
    Q_D(QCompleter);
    return d->proxy->setCurrentRow(row);
}

setMaxVisibleItems()

void QCompleter::setMaxVisibleItems

(

int

maxItems

)

Definition at line 1611 of file qcompleter.cpp.

{
    Q_D(QCompleter);
    if (maxItems < 0) {
        qWarning("QCompleter::setMaxVisibleItems: "
                 "Invalid max visible items (%d) must be >= 0", maxItems);
        return;
    }
    d->maxVisibleItems = maxItems;
}

setModel()

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}

Definition at line 1025 of file qcompleter.cpp.

{
    Q_D(QCompleter);
    QAbstractItemModel *oldModel = d->proxy->sourceModel();
    d->proxy->setSourceModel(model);
    if (d->popup)
        setPopup(d->popup); // set the model and make new connections
    if (oldModel && oldModel->QObject::parent() == this)
        delete oldModel;
#ifndef QT_NO_DIRMODEL
    if (qobject_cast<QDirModel *>(model)) {
#if (defined(Q_OS_WIN) && !defined(Q_OS_WINCE)) || defined(Q_OS_SYMBIAN)
        setCaseSensitivity(Qt::CaseInsensitive);
#else
        setCaseSensitivity(Qt::CaseSensitive);
#endif
    }
#endif // QT_NO_DIRMODEL
#ifndef QT_NO_FILESYSTEMMODEL
    QFileSystemModel *fsModel = qobject_cast<QFileSystemModel *>(model);
    if (fsModel) {
#if (defined(Q_OS_WIN) && !defined(Q_OS_WINCE)) || defined(Q_OS_SYMBIAN)
        setCaseSensitivity(Qt::CaseInsensitive);
#else
        setCaseSensitivity(Qt::CaseSensitive);
#endif
        setCompletionRole(QFileSystemModel::FileNameRole);
        connect(fsModel, SIGNAL(directoryLoaded(QString)), this, SLOT(_q_fileSystemModelDirectoryLoaded(QString)));
    }
#endif // QT_NO_FILESYSTEMMODEL
}

setModelSorting()

void QCompleter::setModelSorting

(

QCompleter::ModelSorting

sorting

)

Definition at line 1496 of file qcompleter.cpp.

{
    Q_D(QCompleter);
    if (d->sorting == sorting)
        return;
    d->sorting = sorting;
    d->proxy->createEngine();
    d->proxy->invalidate();
}

setPopup()

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

Definition at line 1132 of file qcompleter.cpp.

Referenced by popup(), and setModel().

{
    Q_D(QCompleter);
    Q_ASSERT(popup != 0);
    if (d->popup) {
        QObject::disconnect(d->popup->selectionModel(), 0, this, 0);
        QObject::disconnect(d->popup, 0, this, 0);
    }
    if (d->popup != popup)
        delete d->popup;
    if (popup->model() != d->proxy)
        popup->setModel(d->proxy);
#if defined(Q_OS_MAC) && !defined(QT_MAC_USE_COCOA)
     popup->show();
#else
     popup->hide();
#endif

    Qt::FocusPolicy origPolicy = Qt::NoFocus;
    if (d->widget)
        origPolicy = d->widget->focusPolicy();
    popup->setParent(0, Qt::Popup);
    popup->setFocusPolicy(Qt::NoFocus);
    if (d->widget)
        d->widget->setFocusPolicy(origPolicy);

    popup->setFocusProxy(d->widget);
    popup->installEventFilter(this);
    popup->setItemDelegate(new QCompleterItemDelegate(popup));
#ifndef QT_NO_LISTVIEW
    if (QListView *listView = qobject_cast<QListView *>(popup)) {
        listView->setModelColumn(d->column);
    }
#endif

    QObject::connect(popup, SIGNAL(clicked(QModelIndex)),
                     this, SLOT(_q_complete(QModelIndex)));
    QObject::connect(this, SIGNAL(activated(QModelIndex)),
                     popup, SLOT(hide()));

    QObject::connect(popup->selectionModel(), SIGNAL(selectionChanged(QItemSelection,QItemSelection)),
                     this, SLOT(_q_completionSelected(QItemSelection)));
    d->popup = popup;
}

setWidget()

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

Definition at line 989 of file qcompleter.cpp.

Referenced by QLineEdit::setCompleter(), and QComboBox::setCompleter().

{
    Q_D(QCompleter);
    if (d->widget)
        d->widget->removeEventFilter(this);
    d->widget = widget;
    if (d->widget)
        d->widget->installEventFilter(this);
    if (d->popup) {
        d->popup->hide();
        d->popup->setFocusProxy(d->widget);
    }
}

setWrapAround

void QCompleter::setWrapAround ( bool  wrap )

slot

Definition at line 1581 of file qcompleter.cpp.

{
    Q_D(QCompleter);
    if (d->wrap == wrap)
        return;
    d->wrap = wrap;
}

splitPath()

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}

Reimplemented in QFSCompleter.

Definition at line 1780 of file qcompleter.cpp.

Referenced by setCompletionPrefix().

{
    bool isDirModel = false;
    bool isFsModel = false;
#ifndef QT_NO_DIRMODEL
    Q_D(const QCompleter);
    isDirModel = qobject_cast<QDirModel *>(d->proxy->sourceModel()) != 0;
#endif
#ifndef QT_NO_FILESYSTEMMODEL
#ifdef QT_NO_DIRMODEL
    Q_D(const QCompleter);
#endif
    isFsModel = qobject_cast<QFileSystemModel *>(d->proxy->sourceModel()) != 0;
#endif

    if ((!isDirModel && !isFsModel) || path.isEmpty())
        return QStringList(completionPrefix());

    QString pathCopy = QDir::toNativeSeparators(path);
    QString sep = QDir::separator();
#if defined(Q_OS_SYMBIAN)
    if (pathCopy == QLatin1String("\\"))
        return QStringList(pathCopy);
#elif defined(Q_OS_WIN) && !defined(Q_OS_WINCE)
    if (pathCopy == QLatin1String("\\") || pathCopy == QLatin1String("\\\\"))
        return QStringList(pathCopy);
    QString doubleSlash(QLatin1String("\\\\"));
    if (pathCopy.startsWith(doubleSlash))
        pathCopy = pathCopy.mid(2);
    else
        doubleSlash.clear();
#endif

    QRegExp re(QLatin1Char('[') + QRegExp::escape(sep) + QLatin1Char(']'));
    QStringList parts = pathCopy.split(re);

#if defined(Q_OS_SYMBIAN)
    // Do nothing
#elif defined(Q_OS_WIN) && !defined(Q_OS_WINCE)
    if (!doubleSlash.isEmpty())
        parts[0].prepend(doubleSlash);
#else
    if (pathCopy[0] == sep[0]) // readd the "/" at the beginning as the split removed it
        parts[0] = QDir::fromNativeSeparators(QString(sep[0]));
#endif

    return parts;
}

widget()

QWidget * QCompleter::widget

(

)

const

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

See also

setWidget()

Definition at line 1008 of file qcompleter.cpp.

Referenced by QLineEdit::setCompleter(), and setWidget().

{
    Q_D(const QCompleter);
    return d->widget;
}

wrapAround()

bool QCompleter::wrapAround

(

)

const

Referenced by setWrapAround().

Properties

caseSensitivity

Qt::CaseSensitivity QCompleter::caseSensitivity

private

the case sensitivity of the matching

The default is Qt::CaseSensitive.

See also

completionColumn, completionRole, modelSorting

Definition at line 73 of file qcompleter.h.

Referenced by QLineControl::complete(), and QComboBoxPrivate::matchFlags().

completionColumn

int QCompleter::completionColumn

private

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

Definition at line 70 of file qcompleter.h.

completionMode

QCompleter::CompletionMode QCompleter::completionMode

private

how the completions are provided to the user

The default value is QCompleter::PopupCompletion.

Definition at line 69 of file qcompleter.h.

Referenced by QLineEditPrivate::_q_completionHighlighted(), QLineEditPrivate::_q_textEdited(), QLineControl::complete(), and QLineControl::processKeyEvent().

completionPrefix

QString QCompleter::completionPrefix

private

the completion prefix used to provide completions.

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

Definition at line 67 of file qcompleter.h.

Referenced by QLineControl::complete().

completionRole

int QCompleter::completionRole

private

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

The default role is Qt::EditRole.

See also

completionColumn, caseSensitivity

Definition at line 71 of file qcompleter.h.

maxVisibleItems

int QCompleter::maxVisibleItems

private

the maximum allowed size on screen of the completer, measured in items

Since

4.6

By default, this property has a value of 7.

Definition at line 72 of file qcompleter.h.

modelSorting

QCompleter::ModelSorting QCompleter::modelSorting

private

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 cannot 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

Definition at line 68 of file qcompleter.h.

wrapAround

bool QCompleter::wrapAround

private

the completions wrap around when navigating through items

Since

4.3

The default is true.

Definition at line 74 of file qcompleter.h.

Referenced by QLineControl::advanceToEnabledItem().

---

The documentation for this class was generated from the following files:

• /src/gui/util/qcompleter.h
• /src/gui/util/qcompleter.cpp