|  | Home · Overviews · Examples

# QCompleter Class Reference
[com.trolltech.qt.gui module]

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

Inherits `QObject`.

## Detailed Description

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
- Iterating Through Completions
- The Completion Model
- Handling Tree Models

### 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`, and Completer Example.