Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.trolltech.qt.gui
Class QCompleter

    java.lang.Object
      com.trolltech.qt.internal.QSignalEmitterInternal
          com.trolltech.qt.QSignalEmitter
              com.trolltech.qt.QtJambiObject
                  com.trolltech.qt.core.QObject
                      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
- 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`:

            List<String> wordList = new Vector<String>();
            wordList.add("alpha");
            wordList.add("omega");
            wordList.add("omicron");
            wordList.add("zeta");

            QLineEdit lineEdit = new QLineEdit();

            QCompleter completer = new QCompleter(wordList);
            completer.setCaseSensitivity(Qt.CaseSensitivity.CaseInsensitive);
            lineEdit.setCompleter(completer);

A `QDirModel` can be used to provide auto completion of file names. For example:

            QCompleter completer2 = new QCompleter();
            completer2.setModel(new QDirModel(completer2));
            lineEdit.setCompleter(completer2);

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++)
                    System.out.println(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.

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, QSignalEmitter.Signal2, QSignalEmitter.Signal3, QSignalEmitter.Signal4, QSignalEmitter.Signal5, QSignalEmitter.Signal6, QSignalEmitter.Signal7, QSignalEmitter.Signal8, QSignalEmitter.Signal9`

Nested classes/interfaces inherited from class com.trolltech.qt.internal.QSignalEmitterInternal
`com.trolltech.qt.internal.QSignalEmitterInternal.AbstractSignalInternal`

Field Summary
`QSignalEmitter.Signal1` | `activated` This signal takes 1 generic argument(s).
`QSignalEmitter.Signal1` | `activatedIndex` This signal takes 1 generic argument(s).
`QSignalEmitter.Signal1` | `highlighted` This signal takes 1 generic argument(s).
`QSignalEmitter.Signal1` | `highlightedIndex` This signal takes 1 generic argument(s).

Fields inherited from class com.trolltech.qt.internal.QSignalEmitterInternal
`currentSender`

Constructor Summary
`QCompleter()` Constructs a completer object with the given `parent`.
`QCompleter(java.util.List completions)` Constructs a `QCompleter` object with the given `parent` that uses the specified `list` as a source of possible completions.
`QCompleter(java.util.List completions, QObject parent)` Constructs a `QCompleter` object with the given `parent` that uses the specified `list` as a source of possible completions.
`QCompleter(QAbstractItemModel model)` Constructs a completer object with the given `parent` that provides completions from the specified `model`.
`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()` This property holds the case sensitivity of the matching.
`void` | `complete()` For `QCompleter::PopupCompletion` and QCompletion::UnfilteredPopupCompletion modes, calling this function displays the popup displaying the current completions.
`void` | `complete(QRect rect)` For `QCompleter::PopupCompletion` and QCompletion::UnfilteredPopupCompletion modes, calling this function displays the popup displaying the current completions.
`int` | `completionColumn()` This property holds 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()` This property holds how the completions are provided to the user.
`QAbstractItemModel` | `completionModel()` Returns the completion model.
`java.lang.String` | `completionPrefix()` This property holds the completion prefix used to provide completions.
`int` | `completionRole()` This property holds the item role to be used to query the contents of items for matching.
`java.lang.String` | `currentCompletion()` Returns the current completion string.
`com.trolltech.qt.core.QModelIndex` | `currentIndex()` Returns the model index of the current completion in the `completionModel()`.
`int` | `currentRow()` Returns the current row.
`QAbstractItemModel` | `model()` Returns the model that provides completion strings.
`QCompleter.ModelSorting` | `modelSorting()` This property holds the way the model is sorted.
`java.lang.String` | `pathFromIndex(com.trolltech.qt.core.QModelIndex index)` Returns the path for the given `index`.
`QAbstractItemView` | `popup()` Returns the popup used to display completions.
`void` | `setCaseSensitivity(Qt.CaseSensitivity caseSensitivity)` This property holds the case sensitivity of the matching.
`void` | `setCompletionColumn(int column)` This property holds the column in the model in which completions are searched for.
`void` | `setCompletionMode(QCompleter.CompletionMode mode)` This property holds how the completions are provided to the user.
`void` | `setCompletionPrefix(java.lang.String prefix)` This property holds the completion prefix used to provide completions.
`void` | `setCompletionRole(int role)` This property holds 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 `model`.
`void` | `setModelSorting(QCompleter.ModelSorting sorting)` This property holds the way the model is sorted.
`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)` This property holds the completions wrap around when navigating through items.
`java.util.List` | `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()` This property holds the completions wrap around when navigating through items.

Methods inherited from class com.trolltech.qt.core.QObject
`childEvent, children, connectSlotsByName, customEvent, disposeLater, dumpObjectInfo, dumpObjectTree, dynamicPropertyNames, event, eventFilter, findChild, findChild, findChild, findChildren, findChildren, findChildren, findChildren, indexOfProperty, installEventFilter, isWidgetType, killTimer, moveToThread, objectName, parent, properties, property, removeEventFilter, setObjectName, setParent, setProperty, startTimer, timerEvent, toString, userProperty`

Methods inherited from class com.trolltech.qt.QtJambiObject
`dispose, disposed, equals, finalize, reassignNativeResources, tr, tr, tr`

Methods inherited from class com.trolltech.qt.QSignalEmitter
`blockSignals, disconnect, disconnect, signalsBlocked, signalSender, thread`

Methods inherited from class com.trolltech.qt.internal.QSignalEmitterInternal
`__qt_signalInitialization`

Methods inherited from class java.lang.Object
`clone, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Methods inherited from interface com.trolltech.qt.QtJambiInterface
`disableGarbageCollection, nativeId, nativePointer, reenableGarbageCollection, setJavaOwnership`

Field Detail

### activatedIndex

    public final QSignalEmitter.Signal1 activatedIndex

  This signal takes 1 generic argument(s). We list their type and the name they go by in the description of this signal. <com.trolltech.qt.core.QModelIndex(named: text)>:

  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.

### activated

    public final QSignalEmitter.Signal1 activated

  This signal takes 1 generic argument(s). We list their type and the name they go by in the description of this signal. <java.lang.String(named: text)>:

  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.

### highlightedIndex

    public final QSignalEmitter.Signal1 highlightedIndex

  This signal takes 1 generic argument(s). We list their type and the name they go by in the description of this signal. <com.trolltech.qt.core.QModelIndex(named: text)>:

  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

    public final QSignalEmitter.Signal1 highlighted

  This signal takes 1 generic argument(s). We list their type and the name they go by in the description of this signal. <java.lang.String(named: text)>:

  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.

Constructor Detail

### QCompleter

    public QCompleter(QAbstractItemModel model)

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

### QCompleter

    public QCompleter(QAbstractItemModel model,
                      QObject parent)

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

### QCompleter

    public QCompleter()

  Constructs a completer object with the given `parent`.

### QCompleter

    public QCompleter(QObject parent)

  Constructs a completer object with the given `parent`.

### QCompleter

    public QCompleter(java.util.List completions)

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

### QCompleter

    public QCompleter(java.util.List completions,
                      QObject parent)

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

Method Detail

### caseSensitivity

    public final Qt.CaseSensitivity caseSensitivity()

  This property holds the case sensitivity of the matching. The default is `Qt::CaseSensitive` .

See also:
  `completionColumn`, `completionRole`, and `modelSorting`.

### complete

    public final void complete()

  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.

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

  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`, and `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()

  This property holds how the completions are provided to the user. The default value is `QCompleter::PopupCompletion` .

### 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`, and `model()`.

### completionPrefix

    public final java.lang.String completionPrefix()

  This property holds the completion prefix used to provide completions. The `completionModel()` is updated to reflect the list of possible matches for `prefix`.

### completionRole

    public final int 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`, and `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()`, and `currentIndex()`.

### currentIndex

    public final com.trolltech.qt.core.QModelIndex currentIndex()

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

See also:
  `setCurrentRow()`, `currentCompletion()`, and `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()`, and `completionModel()`.

### modelSorting

    public final QCompleter.ModelSorting 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 cannot take place when the completer's `caseSensitivity` is different to the case sensitivity used by the model's when sorting.

See also:
  `setCaseSensitivity()`, and `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)

  This property holds the case sensitivity of the matching. The default is `Qt::CaseSensitive` .

See also:
  `completionColumn`, `completionRole`, and `modelSorting`.

### setCompletionColumn

    public final void setCompletionColumn(int column)

  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`, and `caseSensitivity`.

### setCompletionMode

    public final void setCompletionMode(QCompleter.CompletionMode mode)

  This property holds how the completions are provided to the user. The default value is `QCompleter::PopupCompletion` .

### setCompletionPrefix

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

  This property holds the completion prefix used to provide completions. The `completionModel()` is updated to reflect the list of possible matches for `prefix`.

### setCompletionRole

    public final void setCompletionRole(int role)

  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`, and `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()`, and `completionCount()`.

### setModel

    public final void setModel(QAbstractItemModel c)

  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 `QDirModel`, `QCompleter` switches its `caseSensitivity` to `Qt::CaseInsensitive` on Windows and `Qt::CaseSensitive` on other platforms.

See also:
  `completionModel()`, `modelSorting`, and `Handling Tree Models`.

### setModelSorting

    public final void setModelSorting(QCompleter.ModelSorting sorting)

  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 cannot take place when the completer's `caseSensitivity` is different to the case sensitivity used by the model's when sorting.

See also:
  `setCaseSensitivity()`, and `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()`, and `setPopup()`.

### setWrapAround

    public final void setWrapAround(boolean wrap)

  This property holds the completions wrap around when navigating through items. The default is true.

### widget

    public final QWidget widget()

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

See also:
  `setWidget()`.

### wrapAround

    public final boolean wrapAround()

  This property holds the completions wrap around when navigating through items. The default is true.

### pathFromIndex

    public java.lang.String pathFromIndex(com.trolltech.qt.core.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 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()`, and `Handling Tree Models`.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD