QCompleter Class

Die Klasse QCompleter bietet Vervollständigungen auf der Grundlage eines Objektmodells. Mehr...

Kopfzeile: #include <QCompleter>
CMake: find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake: QT += widgets
Vererbt: QObject

Öffentliche Typen

enum CompletionMode { PopupCompletion, InlineCompletion, UnfilteredPopupCompletion }
enum ModelSorting { UnsortedModel, CaseSensitivelySortedModel, CaseInsensitivelySortedModel }

Eigenschaften

Öffentliche Funktionen

QCompleter(QObject *parent = nullptr)
QCompleter(QAbstractItemModel *model, QObject *parent = nullptr)
QCompleter(const QStringList &list, QObject *parent = nullptr)
virtual ~QCompleter() override
Qt::CaseSensitivity caseSensitivity() const
int completionColumn() const
int completionCount() const
QCompleter::CompletionMode completionMode() const
QAbstractItemModel *completionModel() const
QString completionPrefix() const
int completionRole() const
QString currentCompletion() const
QModelIndex currentIndex() const
int currentRow() const
Qt::MatchFlags filterMode() const
int maxVisibleItems() const
QAbstractItemModel *model() const
QCompleter::ModelSorting modelSorting() const
virtual QString pathFromIndex(const QModelIndex &index) const
QAbstractItemView *popup() const
void setCaseSensitivity(Qt::CaseSensitivity caseSensitivity)
void setCompletionColumn(int column)
void setCompletionMode(QCompleter::CompletionMode mode)
void setCompletionRole(int role)
bool setCurrentRow(int row)
void setFilterMode(Qt::MatchFlags filterMode)
void setMaxVisibleItems(int maxItems)
void setModel(QAbstractItemModel *model)
void setModelSorting(QCompleter::ModelSorting sorting)
void setPopup(QAbstractItemView *popup)
void setWidget(QWidget *widget)
virtual QStringList splitPath(const QString &path) const
QWidget *widget() const
bool wrapAround() const

Öffentliche Slots

void complete(const QRect &rect = QRect())
void setCompletionPrefix(const QString &prefix)
void setWrapAround(bool wrap)

Signale

void activated(const QModelIndex &index)
void activated(const QString &text)
void highlighted(const QModelIndex &index)
void highlighted(const QString &text)

Reimplementierte geschützte Funktionen

virtual bool event(QEvent *ev) override
virtual bool eventFilter(QObject *o, QEvent *e) override

Detaillierte Beschreibung

Sie können QCompleter verwenden, um automatische Vervollständigungen in jedem Qt-Widget, wie QLineEdit und QComboBox, anzubieten. Wenn der Benutzer mit der Eingabe eines Wortes beginnt, schlägt QCompleter mögliche Vervollständigungen des Wortes vor, die auf einer Wortliste basieren. Die Wortliste wird als QAbstractItemModel bereitgestellt. (Für einfache Anwendungen, bei denen die Wortliste statisch ist, können Sie dem Konstruktor von QCompleter eine QStringList übergeben).

Grundlegende Verwendung

Ein QCompleter wird typischerweise mit einem QLineEdit oder QComboBox verwendet. Hier ein Beispiel, wie man automatische Vervollständigungen aus einer einfachen Wortliste in einem QLineEdit bereitstellt:

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

Ein QFileSystemModel kann für die automatische Vervollständigung von Dateinamen verwendet werden. Zum Beispiel:

QCompleter *completer = new QCompleter(this);
completer->setModel(new QFileSystemModel(completer));
lineEdit->setCompleter(completer);

Um das Modell festzulegen, mit dem QCompleter arbeiten soll, rufen Sie setModel() auf. Standardmäßig versucht QCompleter, die completion prefix (d.h. das Wort, das der Benutzer zu tippen begonnen hat) mit den Qt::EditRole Daten abzugleichen, die in Spalte 0 des Modells unter Berücksichtigung der Groß- und Kleinschreibung gespeichert sind. Dies kann mit setCompletionRole(), setCompletionColumn() und setCaseSensitivity() geändert werden.

Wenn das Modell nach der Spalte und der Rolle sortiert ist, die für die Vervollständigung verwendet werden, können Sie setModelSorting() entweder mit QCompleter::CaseSensitivelySortedModel oder QCompleter::CaseInsensitivelySortedModel als Argument aufrufen. Bei großen Modellen kann dies zu erheblichen Leistungsverbesserungen führen, da QCompleter dann eine binäre Suche anstelle einer linearen Suche verwenden kann. Die binäre Suche funktioniert nur, wenn die filterMode Qt::MatchStartsWith ist.

Das Modell kann ein list model, ein table model oder ein tree model sein. Die Vervollständigung von Baummodellen ist etwas komplizierter und wird im folgenden Abschnitt Handling Tree Models behandelt.

Der completionMode() bestimmt den Modus, in dem dem Benutzer Vervollständigungen angeboten werden.

Iteration durch Vervollständigungen

Um eine einzelne Kandidatenzeichenkette abzurufen, rufen Sie setCompletionPrefix() mit dem Text auf, der vervollständigt werden soll, und rufen Sie currentCompletion() auf. Sie können die Liste der Vervollständigungen wie folgt durchlaufen:

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

completionCount() gibt die Gesamtzahl der Vervollständigungen für das aktuelle Präfix zurück. completionCount() sollte nach Möglichkeit vermieden werden, da sie eine Überprüfung des gesamten Modells erfordert.

Das Vervollständigungsmodell

completionModel() gibt ein Listenmodell zurück, das alle möglichen Vervollständigungen für das aktuelle Vervollständigungspräfix enthält, und zwar in der Reihenfolge, in der sie im Modell erscheinen. Dieses Modell kann verwendet werden, um die aktuellen Vervollständigungen in einer benutzerdefinierten Ansicht anzuzeigen. Durch den Aufruf von setCompletionPrefix() wird das Vervollständigungsmodell automatisch aktualisiert.

Behandlung von Baummodellen

QCompleter kann in Baummodellen nach Vervollständigungen suchen, wobei davon ausgegangen wird, dass jedes Element (oder Unterelement oder Unter-Unterelement) eindeutig als String dargestellt werden kann, indem der Pfad zum Element angegeben wird. Die Vervollständigung wird dann Ebene für Ebene durchgeführt.

Nehmen wir das Beispiel eines Benutzers, der einen Dateisystempfad eintippt. Das Modell ist ein (hierarchisches) QFileSystemModel. Die Vervollständigung erfolgt für jedes Element des Pfades. Wenn der aktuelle Text zum Beispiel C:\Wind ist, könnte QCompleter Windows vorschlagen, um das aktuelle Pfadelement zu vervollständigen. Ähnlich könnte QCompleter System vorschlagen, wenn der aktuelle Text C:\Windows\Sy ist.

Damit diese Art der Vervollständigung funktioniert, muss QCompleter in der Lage sein, den Pfad in eine Liste von Strings aufzuteilen, die auf jeder Ebene abgeglichen werden. Für C:\Windows\Sy muss der Pfad in "C:", "Windows" und "Sy" aufgeteilt werden. Die Standardimplementierung von splitPath() teilt completionPrefix mit QDir::separator() auf, wenn das Modell ein QFileSystemModel ist.

Um Vervollständigungen bereitzustellen, muss QCompleter den Pfad von einem Index kennen. Dies wird durch pathFromIndex() bereitgestellt. Die Standardimplementierung von pathFromIndex() gibt die Daten für edit role für Listenmodelle und den absoluten Dateipfad zurück, wenn der Modus ein QFileSystemModel ist.

Siehe auch QAbstractItemModel, QLineEdit, QComboBox, und Completer Example.

Dokumentation der Mitgliedstypen

enum QCompleter::CompletionMode

Diese Aufzählung gibt an, wie Vervollständigungen für den Benutzer bereitgestellt werden.

KonstanteWertBeschreibung
QCompleter::PopupCompletion0Aktuelle Vervollständigungen werden in einem Popup-Fenster angezeigt.
QCompleter::InlineCompletion2Vervollständigungen erscheinen inline (als markierter Text).
QCompleter::UnfilteredPopupCompletion1Alle möglichen Vervollständigungen werden in einem Popup-Fenster angezeigt, wobei der wahrscheinlichste Vorschlag als aktuell angezeigt wird.

Siehe auch setCompletionMode().

enum QCompleter::ModelSorting

Diese Aufzählung gibt an, wie die Elemente im Modell sortiert sind.

KonstanteWertBeschreibung
QCompleter::UnsortedModel0Das Modell ist unsortiert.
QCompleter::CaseSensitivelySortedModel1Das Modell ist nach Groß- und Kleinschreibung sortiert.
QCompleter::CaseInsensitivelySortedModel2Das Modell ist unsensibel sortiert.

Siehe auch setModelSorting().

Eigenschaft Dokumentation

caseSensitivity : Qt::CaseSensitivity

Diese Eigenschaft bestimmt die Groß- und Kleinschreibung bei der Suche.

Der Standardwert ist Qt::CaseSensitive.

Zugriffsfunktionen:

Qt::CaseSensitivity caseSensitivity() const
void setCaseSensitivity(Qt::CaseSensitivity caseSensitivity)

Siehe auch completionColumn, completionRole, modelSorting, und filterMode.

completionColumn : int

Diese Eigenschaft enthält die Spalte im Modell, in der nach Vervollständigungen gesucht wird.

Wenn die popup() eine QListView ist, wird sie automatisch so eingerichtet, dass diese Spalte angezeigt wird.

Standardmäßig ist die Übereinstimmungsspalte 0.

Zugriffsfunktionen:

int completionColumn() const
void setCompletionColumn(int column)

Siehe auch completionRole und caseSensitivity.

completionMode : CompletionMode

wie die Ausfüllungen dem Benutzer zur Verfügung gestellt werden

Der Standardwert ist QCompleter::PopupCompletion.

Zugriffsfunktionen:

QCompleter::CompletionMode completionMode() const
void setCompletionMode(QCompleter::CompletionMode mode)

completionPrefix : QString

Diese Eigenschaft enthält das Vervollständigungspräfix, das zur Bereitstellung von Vervollständigungen verwendet wird.

Die completionModel() wird aktualisiert, um die Liste der möglichen Übereinstimmungen für prefix wiederzugeben.

Zugriffsfunktionen:

QString completionPrefix() const
void setCompletionPrefix(const QString &prefix)

completionRole : int

Diese Eigenschaft enthält die Elementrolle, die zur Abfrage des Inhalts von Elementen für den Abgleich verwendet werden soll.

Die Standardrolle ist Qt::EditRole.

Zugriffsfunktionen:

int completionRole() const
void setCompletionRole(int role)

Siehe auch completionColumn und caseSensitivity.

filterMode : Qt::MatchFlags

Diese Eigenschaft steuert, wie die Filterung durchgeführt wird.

Wenn filterMode auf Qt::MatchStartsWith gesetzt ist, werden nur die Einträge angezeigt, die mit den eingegebenen Zeichen beginnen. Qt::MatchContains zeigt die Einträge an, die die eingegebenen Zeichen enthalten, und Qt::MatchEndsWith diejenigen, die mit den eingegebenen Zeichen enden.

Wird filterMode auf einen anderen Qt::MatchFlag gesetzt, wird eine Warnung ausgegeben und keine Aktion durchgeführt. Aus diesem Grund hat das Qt::MatchCaseSensitive Flag keine Auswirkung. Verwenden Sie die Eigenschaft caseSensitivity, um die Groß- und Kleinschreibung zu steuern.

Der Standardmodus ist Qt::MatchStartsWith.

Zugriff auf Funktionen:

Qt::MatchFlags filterMode() const
void setFilterMode(Qt::MatchFlags filterMode)

Siehe auch caseSensitivity.

maxVisibleItems : int

Diese Eigenschaft enthält die maximal zulässige Bildschirmgröße des Vervollständigers, gemessen in Elementen

Standardmäßig hat diese Eigenschaft einen Wert von 7.

Zugriffsfunktionen:

int maxVisibleItems() const
void setMaxVisibleItems(int maxItems)

modelSorting : ModelSorting

Diese Eigenschaft legt fest, wie das Modell sortiert wird

Standardmäßig werden keine Annahmen über die Reihenfolge der Elemente in dem Modell getroffen, das die Vervollständigungen bereitstellt.

Wenn die Daten des Modells für completionColumn() und completionRole() in aufsteigender Reihenfolge sortiert sind, können Sie diese Eigenschaft auf CaseSensitivelySortedModel oder CaseInsensitivelySortedModel setzen. Bei großen Modellen kann dies zu erheblichen Leistungsverbesserungen führen, da das Vervollständigungsobjekt dann einen binären Suchalgorithmus anstelle eines linearen Suchalgorithmus verwenden kann.

Die Sortierreihenfolge (d. h. auf- oder absteigende Reihenfolge) des Modells wird dynamisch durch Überprüfung des Modellinhalts bestimmt.

Hinweis: Die oben beschriebenen Leistungsverbesserungen können nicht erzielt werden, wenn die caseSensitivity des Completers sich von der Groß- und Kleinschreibung unterscheidet, die das Modell beim Sortieren verwendet.

Zugriffsfunktionen:

QCompleter::ModelSorting modelSorting() const
void setModelSorting(QCompleter::ModelSorting sorting)

Siehe auch setCaseSensitivity() und QCompleter::ModelSorting.

wrapAround : bool

Diese Eigenschaft legt fest, dass die Vervollständigungen beim Navigieren durch die Elemente umbrochen werden

Der Standardwert ist true.

Zugriffsfunktionen:

bool wrapAround() const
void setWrapAround(bool wrap)

Dokumentation der Mitgliedsfunktionen

QCompleter::QCompleter(QObject *parent = nullptr)

Konstruiert ein Completer-Objekt mit der angegebenen parent.

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

Konstruiert ein Completion-Objekt mit dem angegebenen parent, das Vervollständigungen aus dem angegebenen model liefert.

QCompleter::QCompleter(const QStringList &list, QObject *parent = nullptr)

Konstruiert ein QCompleter-Objekt mit dem angegebenen parent, das die angegebene list als Quelle für mögliche Vervollständigungen verwendet.

[override virtual noexcept] QCompleter::~QCompleter()

Zerstört das Vervollständiger-Objekt.

[signal] void QCompleter::activated(const QModelIndex &index)

Dieses Signal wird gesendet, wenn ein Element in popup() vom Benutzer aktiviert wird. (durch Klicken oder Drücken der Return-Taste). Der Eintrag index in completionModel() wird angegeben.

Hinweis: Das Signal activated ist in dieser Klasse überladen. Um sich mit diesem Signal zu verbinden, indem man die Funktionszeigersyntax verwendet, bietet Qt einen praktischen Helfer, um den Funktionszeiger zu erhalten, wie in diesem Beispiel gezeigt:

connect(completer, QOverload<const QModelIndex &>::of(&QCompleter::activated),
    [=](const QModelIndex &index){ /* ... */ });

[signal] void QCompleter::activated(const QString &text)

Dieses Signal wird gesendet, wenn ein Element in popup() vom Benutzer aktiviert wird (durch Klicken oder Drücken der Return-Taste). Es wird die text des Elements angegeben.

Hinweis: Das Signal activated ist in dieser Klasse überladen. Um sich mit diesem Signal zu verbinden, indem man die Funktionszeigersyntax verwendet, bietet Qt einen praktischen Helfer, um den Funktionszeiger zu erhalten, wie in diesem Beispiel gezeigt:

connect(completer, QOverload<const QString &>::of(&QCompleter::activated),
    [=](const QString &text){ /* ... */ });

[slot] void QCompleter::complete(const QRect &rect = QRect())

Für die Modi QCompleter::PopupCompletion und QCompletion::UnfilteredPopupCompletion wird durch den Aufruf dieser Funktion das Popup mit den aktuellen Vervollständigungen angezeigt. Wenn rect nicht angegeben ist, wird das Popup standardmäßig am unteren Rand von widget() angezeigt. Wenn rect angegeben ist, wird das Popup am linken Rand des Rechtecks angezeigt.

Im Modus QCompleter::InlineCompletion wird das Signal highlighted() mit der aktuellen Fertigstellung ausgelöst.

int QCompleter::completionCount() const

Gibt die Anzahl der Vervollständigungen für das aktuelle Präfix zurück. Bei einem unsortierten Modell mit einer großen Anzahl von Elementen kann dies teuer werden. Verwenden Sie setCurrentRow() und currentCompletion(), um durch alle Vervollständigungen zu iterieren.

QAbstractItemModel *QCompleter::completionModel() const

Gibt das Vervollständigungsmodell zurück. Das Vervollständigungsmodell ist ein schreibgeschütztes Listenmodell, das alle möglichen Übereinstimmungen mit dem aktuellen Vervollständigungspräfix enthält. Das Vervollständigungsmodell wird automatisch aktualisiert, um die aktuellen Vervollständigungen wiederzugeben.

Hinweis: Der Rückgabewert dieser Funktion ist rein aus Gründen der Allgemeinheit als QAbstractItemModel definiert. Die tatsächliche Art des zurückgegebenen Modells ist eine Instanz einer QAbstractProxyModel Unterklasse.

Siehe auch completionPrefix und model().

QString QCompleter::currentCompletion() const

Gibt die aktuelle Abschlusszeichenfolge zurück. Dies schließt die completionPrefix ein. Zusammen mit setCurrentRow() kann diese Funktion verwendet werden, um alle Übereinstimmungen zu durchlaufen.

Siehe auch setCurrentRow() und currentIndex().

QModelIndex QCompleter::currentIndex() const

Gibt den Modellindex des aktuellen Abschlusses in completionModel() zurück.

Siehe auch setCurrentRow(), currentCompletion(), und model().

int QCompleter::currentRow() const

Gibt die aktuelle Zeile zurück.

Siehe auch setCurrentRow().

[override virtual protected] bool QCompleter::event(QEvent *ev)

Reimplements: QObject::event(QEvent *e).

[override virtual protected] bool QCompleter::eventFilter(QObject *o, QEvent *e)

Reimplements: QObject::eventFilter(QObject *watched, QEvent *event).

[signal] void QCompleter::highlighted(const QModelIndex &index)

Dieses Signal wird gesendet, wenn ein Element in popup() vom Benutzer hervorgehoben wird. Es wird auch gesendet, wenn complete() aufgerufen wird, während completionMode() auf QCompleter::InlineCompletion gesetzt ist. Das Element index in completionModel() wird angegeben.

Hinweis: Das Signal highlighted ist in dieser Klasse überladen. Um sich mit diesem Signal zu verbinden, indem man die Funktionszeigersyntax verwendet, bietet Qt einen praktischen Helfer, um den Funktionszeiger zu erhalten, wie in diesem Beispiel gezeigt:

connect(completer, QOverload<const QModelIndex &>::of(&QCompleter::highlighted),
    [=](const QModelIndex &index){ /* ... */ });

[signal] void QCompleter::highlighted(const QString &text)

Dieses Signal wird gesendet, wenn ein Element in popup() vom Benutzer hervorgehoben wird. Es wird auch gesendet, wenn complete() aufgerufen wird, während completionMode() auf QCompleter::InlineCompletion gesetzt ist. Die text des Elements wird angegeben.

Hinweis: Das Signal highlighted ist in dieser Klasse überladen. Um sich mit diesem Signal zu verbinden, indem man die Funktionszeiger-Syntax verwendet, bietet Qt einen praktischen Helfer, um den Funktionszeiger zu erhalten, wie in diesem Beispiel gezeigt:

connect(completer, QOverload<const QString &>::of(&QCompleter::highlighted),
    [=](const QString &text){ /* ... */ });

QAbstractItemModel *QCompleter::model() const

Gibt das Modell zurück, das Vervollständigungszeichenfolgen liefert.

Siehe auch setModel() und completionModel().

[virtual] QString QCompleter::pathFromIndex(const QModelIndex &index) const

Gibt den Pfad für den angegebenen index zurück. Das Completer-Objekt verwendet dies, um den Vervollständigungstext aus dem zugrunde liegenden Modell zu erhalten.

Die Standardimplementierung gibt bei Listenmodellen den edit role des Elements zurück. Sie gibt den absoluten Dateipfad zurück, wenn das Modell ein QFileSystemModel ist.

Siehe auch splitPath().

Gibt das Popup zurück, das zur Anzeige von Vervollständigungen verwendet wird.

Siehe auch setPopup().

bool QCompleter::setCurrentRow(int row)

Setzt die aktuelle Zeile auf die angegebene row. Gibt bei Erfolg true zurück, andernfalls false.

Diese Funktion kann zusammen mit currentCompletion() verwendet werden, um alle möglichen Abschlüsse zu durchlaufen.

Siehe auch currentRow(), currentCompletion(), und completionCount().

void QCompleter::setModel(QAbstractItemModel *model)

Legt das Modell fest, das Vervollständigungen für model bereitstellt. model kann ein Listenmodell oder ein Baummodell sein. Wenn ein Modell bereits zuvor festgelegt wurde und QCompleter als Elternteil hat, wird es gelöscht.

Der Einfachheit halber, wenn model ein QFileSystemModel ist, schaltet QCompleter sein caseSensitivity auf Qt::CaseInsensitive unter Windows und Qt::CaseSensitive auf anderen Plattformen.

Siehe auch completionModel(), modelSorting, und Handling Tree Models.

void QCompleter::setPopup(QAbstractItemView *popup)

Setzt das Popup, das zur Anzeige von Abschlüssen verwendet wird, auf popup. QCompleter übernimmt das Eigentum an der Ansicht.

Ein QListView wird automatisch erstellt, wenn completionMode() auf QCompleter::PopupCompletion oder QCompleter::UnfilteredPopupCompletion gesetzt wird. Das Standard-Popup zeigt completionColumn() an.

Stellen Sie sicher, dass diese Funktion aufgerufen wird, bevor die Einstellungen der Ansicht geändert werden. Dies ist erforderlich, da die Eigenschaften der Ansicht erfordern können, dass ein Modell in der Ansicht eingestellt wurde (zum Beispiel erfordert das Ausblenden von Spalten in der Ansicht, dass ein Modell in der Ansicht eingestellt wird).

Siehe auch popup().

void QCompleter::setWidget(QWidget *widget)

Setzt das Widget, für das Vervollständigungen bereitgestellt werden, auf widget. Diese Funktion wird automatisch aufgerufen, wenn ein QCompleter auf einem QLineEdit mit QLineEdit::setCompleter() oder auf einem QComboBox mit QComboBox::setCompleter() gesetzt wird. Das Widget muss explizit gesetzt werden, wenn Vervollständigungen für benutzerdefinierte Widgets bereitgestellt werden.

Siehe auch widget(), setModel(), und setPopup().

[virtual] QStringList QCompleter::splitPath(const QString &path) const

Zerlegt die angegebene path in Zeichenketten, die für die Übereinstimmung auf jeder Ebene in der model() verwendet werden.

Die Standardimplementierung von splitPath() teilt einen Dateisystempfad basierend auf QDir::separator() auf, wenn das sourceModel() ein QFileSystemModel ist.

Bei der Verwendung mit Listenmodellen wird das erste Element in der zurückgegebenen Liste für den Abgleich verwendet.

Siehe auch pathFromIndex() und Handling Tree Models.

QWidget *QCompleter::widget() const

Gibt das Widget zurück, für das das Vervollständiger-Objekt Vervollständigungen bereitstellt.

Siehe auch setWidget().

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.