Qt Jambi Home

com.trolltech.qt.gui
Class QCompleter

java.lang.Object
  extended by com.trolltech.qt.QSignalEmitter
      extended by com.trolltech.qt.QtJambiObject
          extended by com.trolltech.qt.core.QObject
              extended by com.trolltech.qt.gui.QCompleter
All Implemented Interfaces:
QtJambiInterface

public class QCompleter
extends QObject

The QCompleter class provides completions based on an item model.

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

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 completionRole for list models and the absolute file path if the mode is a QDirModel.

See Also:
QAbstractItemModel, QLineEdit, QComboBox, Example

Nested Class Summary
static class QCompleter.CompletionMode
          This enum specifies how completions are provided to the user.
static class QCompleter.ModelSorting
          This enum specifies how the items in the model are sorted.
 
Nested classes/interfaces inherited from class com.trolltech.qt.QSignalEmitter
QSignalEmitter.AbstractSignal, QSignalEmitter.Signal0, QSignalEmitter.Signal1<A>, QSignalEmitter.Signal2<A,B>, QSignalEmitter.Signal3<A,B,C>, QSignalEmitter.Signal4<A,B,C,D>, QSignalEmitter.Signal5<A,B,C,D,E>, QSignalEmitter.Signal6<A,B,C,D,E,F>, QSignalEmitter.Signal7<A,B,C,D,E,F,G>, QSignalEmitter.Signal8<A,B,C,D,E,F,G,H>, QSignalEmitter.Signal9<A,B,C,D,E,F,G,H,I>
 
Field Summary
 QSignalEmitter.Signal1<java.lang.String> activated
          This signal is sent when an item in the popup is activated by the user (by clicking or pressing return).
 QSignalEmitter.Signal1<QModelIndex> activatedIndex
          This signal is sent when an item in the popup is activated by the user.
 QSignalEmitter.Signal1<java.lang.String> highlighted
          This signal is sent when an item in the popup is highlighted by the user.
 QSignalEmitter.Signal1<QModelIndex> highlightedIndex
          This signal is sent when an item in the popup is highlighted by the user.
 
Constructor Summary
QCompleter()
          Equivalent to QCompleter(0).
QCompleter(java.util.List<java.lang.String> completions)
          Equivalent to QCompleter(completions, 0).
QCompleter(java.util.List<java.lang.String> completions, QObject parent)
          Constructs a QCompleter object with the given parent that uses the specified completions as a source of possible completions.
QCompleter(QAbstractItemModel model)
          Equivalent to QCompleter(model, 0).
QCompleter(QAbstractItemModel model, QObject parent)
          Constructs a completer object with the given parent that provides completions from the specified model.
QCompleter(QObject parent)
          Constructs a completer object with the given parent.
 
Method Summary
 Qt.CaseSensitivity caseSensitivity()
          Returns the case sensitivity of the matching.
 void complete()
          Equivalent to complete(QRect()).
 void complete(QRect rect)
          For QCompleter::PopupCompletion and QCompletion::UnfilteredPopupCompletion modes, calling this function displays the popup displaying the current completions.
 int completionColumn()
          Returns the column in the model in which completions are searched for..
 int completionCount()
          Returns the number of completions for the current prefix.
 QCompleter.CompletionMode completionMode()
          Returns how the completions are provided to the user.
 QAbstractItemModel completionModel()
          Returns the completion model.
 java.lang.String completionPrefix()
          Returns the completion prefix used to provide completions..
 int completionRole()
          Returns the item role to be used to query the contents of items for matching..
 java.lang.String currentCompletion()
          Returns the current completion string.
 QModelIndex currentIndex()
          Returns the model index of the current completion in the completionModel.
 int currentRow()
          Returns the current row.
 boolean event(QEvent arg__1)
          This function is reimplemented for internal reasons.
 boolean eventFilter(QObject o, QEvent e)
          This function is reimplemented for internal reasons.
static QCompleter fromNativePointer(QNativePointer nativePointer)
          This function returns the QCompleter instance pointed to by nativePointer
 QAbstractItemModel model()
          Returns the model that provides completion strings.
 QCompleter.ModelSorting modelSorting()
          Returns the way the model is sorted.
 java.lang.String pathFromIndex(QModelIndex index)
          Returns the path for the given index.
 QAbstractItemView popup()
          Returns the popup used to display completions.
 void setCaseSensitivity(Qt.CaseSensitivity caseSensitivity)
          Sets the case sensitivity of the matching to caseSensitivity.
 void setCompletionColumn(int column)
          Sets the column in the model in which completions are searched for.
 void setCompletionMode(QCompleter.CompletionMode mode)
          Sets how the completions are provided to the user to mode.
 void setCompletionPrefix(java.lang.String prefix)
          Sets the completion prefix used to provide completions.
 void setCompletionRole(int role)
          Sets the item role to be used to query the contents of items for matching.
 boolean setCurrentRow(int row)
          Sets the current row to the row specified.
 void setModel(QAbstractItemModel c)
          Sets the model which provides completions to c.
 void setModelSorting(QCompleter.ModelSorting sorting)
          Sets the way the model is sorted to sorting.
 void setPopup(QAbstractItemView popup)
          Sets the popup used to display completions to popup.
 void setWidget(QWidget widget)
          Sets the widget for which completion are provided for to widget.
 void setWrapAround(boolean wrap)
          Sets the completions wrap around when navigating through items to wrap.
 java.util.List<java.lang.String> splitPath(java.lang.String path)
          Splits the given path into strings that are used to match at each level in the model.
 QWidget widget()
          Returns the widget for which the completer object is providing completions.
 boolean wrapAround()
          Returns the completions wrap around when navigating through items.
 
Methods inherited from class com.trolltech.qt.core.QObject
blockSignals, childEvent, children, connectSlotsByName, customEvent, disposeLater, dumpObjectInfo, dumpObjectTree, dynamicPropertyNames, findChild, findChild, findChild, findChildren, findChildren, findChildren, findChildren, installEventFilter, isWidgetType, killTimer, moveToThread, objectName, parent, property, removeEventFilter, setObjectName, setParent, setProperty, signalsBlocked, startTimer, thread, timerEvent
 
Methods inherited from class com.trolltech.qt.QtJambiObject
dispose, disposed, finalize, reassignNativeResources, tr, tr, tr
 
Methods inherited from class com.trolltech.qt.QSignalEmitter
disconnect, disconnect, signalSender
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.trolltech.qt.QtJambiInterface
disableGarbageCollection, nativeId, nativePointer, reenableGarbageCollection, setJavaOwnership
 

Field Detail

activatedIndex

public final QSignalEmitter.Signal1<QModelIndex> activatedIndex

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.

Compatible Slot Signatures:
void mySlot(com.trolltech.qt.core.QModelIndex index)
void mySlot()


activated

public final QSignalEmitter.Signal1<java.lang.String> activated

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.

Compatible Slot Signatures:
void mySlot(java.lang.String text)
void mySlot()


highlightedIndex

public final QSignalEmitter.Signal1<QModelIndex> highlightedIndex

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.

Compatible Slot Signatures:
void mySlot(com.trolltech.qt.core.QModelIndex index)
void mySlot()


highlighted

public final QSignalEmitter.Signal1<java.lang.String> highlighted

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.

Compatible Slot Signatures:
void mySlot(java.lang.String text)
void mySlot()

Constructor Detail

QCompleter

public QCompleter(java.util.List<java.lang.String> completions)

Equivalent to QCompleter(completions, 0).


QCompleter

public QCompleter(java.util.List<java.lang.String> completions,
                  QObject parent)

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


QCompleter

public QCompleter()

Equivalent to QCompleter(0).


QCompleter

public QCompleter(QObject parent)

Constructs a completer object with the given parent.


QCompleter

public QCompleter(QAbstractItemModel model)

Equivalent to QCompleter(model, 0).


QCompleter

public QCompleter(QAbstractItemModel model,
                  QObject parent)

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

Method Detail

caseSensitivity

public final Qt.CaseSensitivity caseSensitivity()

Returns the case sensitivity of the matching.

The default is Qt::CaseSensitive.

See Also:
setCaseSensitivity, completionColumn, completionRole, modelSorting

complete

public final void complete()

Equivalent to complete(QRect()).


complete

public final void complete(QRect rect)

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.


completionColumn

public final int completionColumn()

Returns 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:
setCompletionColumn, completionRole, caseSensitivity

completionCount

public final int completionCount()

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

public final QCompleter.CompletionMode completionMode()

Returns how the completions are provided to the user.

The default value is QCompleter::PopupCompletion.

See Also:
setCompletionMode

completionModel

public final QAbstractItemModel completionModel()

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.

See Also:
completionPrefix, model

completionPrefix

public final java.lang.String completionPrefix()

Returns the completion prefix used to provide completions..

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

See Also:
setCompletionPrefix

completionRole

public final int completionRole()

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

The default role is Qt::EditRole.

See Also:
setCompletionRole, completionColumn, caseSensitivity

currentCompletion

public final java.lang.String currentCompletion()

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

currentIndex

public final QModelIndex currentIndex()

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

See Also:
setCurrentRow, currentCompletion, model

currentRow

public final int currentRow()

Returns the current row.

See Also:
setCurrentRow

model

public final QAbstractItemModel model()

Returns the model that provides completion strings.

See Also:
setModel, completionModel

modelSorting

public final QCompleter.ModelSorting modelSorting()

Returns 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:
setModelSorting, setCaseSensitivity, QCompleter::ModelSorting

popup

public final QAbstractItemView popup()

Returns the popup used to display completions.

See Also:
setPopup

setCaseSensitivity

public final void setCaseSensitivity(Qt.CaseSensitivity caseSensitivity)

Sets the case sensitivity of the matching to caseSensitivity.

The default is Qt::CaseSensitive.

See Also:
caseSensitivity, completionColumn, completionRole, modelSorting

setCompletionColumn

public final void setCompletionColumn(int column)

Sets the column in the model in which completions are searched for. to column.

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

By default, the match column is 0.

See Also:
completionColumn, completionRole, caseSensitivity

setCompletionMode

public final void setCompletionMode(QCompleter.CompletionMode mode)

Sets how the completions are provided to the user to mode.

The default value is QCompleter::PopupCompletion.

See Also:
completionMode

setCompletionPrefix

public final void setCompletionPrefix(java.lang.String prefix)

Sets the completion prefix used to provide completions. to prefix.

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

See Also:
completionPrefix

setCompletionRole

public final void setCompletionRole(int role)

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

The default role is Qt::EditRole.

See Also:
completionRole, completionColumn, caseSensitivity

setCurrentRow

public final boolean 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

setModel

public final void setModel(QAbstractItemModel c)

Sets the model which provides completions to c. The c 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 c is a QDirModel, QCompleter switches its caseSensitivity to Qt::CaseInsensitive on Windows and Qt::CaseSensitive on other platforms.

See Also:
completionModel, modelSorting, Handling Tree Models

setModelSorting

public final void setModelSorting(QCompleter.ModelSorting sorting)

Sets the way the model is sorted to sorting.

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:
modelSorting, setCaseSensitivity, QCompleter::ModelSorting

setPopup

public final void 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

setWidget

public final void 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

setWrapAround

public final void setWrapAround(boolean wrap)

Sets the completions wrap around when navigating through items to wrap.

The default is true.

See Also:
wrapAround

widget

public final QWidget widget()

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

See Also:
setWidget

wrapAround

public final boolean wrapAround()

Returns the completions wrap around when navigating through items.

The default is true.

See Also:
setWrapAround

event

public boolean event(QEvent arg__1)

This function is reimplemented for internal reasons.

Overrides:
event in class QObject
See Also:
installEventFilter, timerEvent, QApplication::sendEvent, QApplication::postEvent, QWidget::event

eventFilter

public boolean eventFilter(QObject o,
                           QEvent e)

This function is reimplemented for internal reasons.

Overrides:
eventFilter in class QObject
See Also:
installEventFilter

pathFromIndex

public java.lang.String pathFromIndex(QModelIndex index)

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

See Also:
splitPath

splitPath

public java.util.List<java.lang.String> splitPath(java.lang.String path)

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

When used with list models, the first item in the returned list is used for matching.

See Also:
pathFromIndex, Handling Tree Models

fromNativePointer

public static QCompleter fromNativePointer(QNativePointer nativePointer)
This function returns the QCompleter instance pointed to by nativePointer

Parameters:
nativePointer - the QNativePointer of which object should be returned.

Qt Jambi Home