En esta página

QCompleter Class

La clase QCompleter ofrece sugerencias basadas en un modelo de elementos. Más información...

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

Tipos públicos

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

Propiedades

Funciones públicas

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

Ranuras públicas

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

Señales

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

Funciones protegidas reimplementadas

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

Descripción detallada

Puedes utilizar QCompleter para ofrecer autocompletado en cualquier widget de Qt, como QLineEdit y QComboBox. Cuando el usuario empieza a escribir una palabra, QCompleter sugiere posibles formas de completarla, basándose en una lista de palabras. La lista de palabras se proporciona como un objeto « QAbstractItemModel ». (Para aplicaciones sencillas, en las que la lista de palabras es estática, se puede pasar un objeto « QStringList » al constructor de QCompleter).

Uso básico

Un QCompleter se utiliza normalmente con un « QLineEdit » o un « QComboBox ». Por ejemplo, a continuación se muestra cómo proporcionar autocompletado a partir de una lista de palabras sencilla en un « 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);

Se puede utilizar un QFileSystemModel para ofrecer autocompletado de nombres de archivos. Por ejemplo:

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

Para configurar el modelo sobre el que debe operar QCompleter, llama a setModel(). Por defecto, QCompleter intentará hacer coincidir el « completion prefix » (es decir, la palabra que el usuario ha empezado a escribir) con los datos del « Qt::EditRole » almacenados en la columna 0 del modelo, distinguiendo entre mayúsculas y minúsculas. Esto se puede modificar utilizando setCompletionRole(), setCompletionColumn() y setCaseSensitivity().

Si el modelo está ordenado según la columna y la función que se utilizan para la autocompletación, puedes llamar a setModelSorting() con QCompleter::CaseSensitivelySortedModel o QCompleter::CaseInsensitivelySortedModel como argumento. En modelos de gran tamaño, esto puede suponer una mejora significativa del rendimiento, ya que QCompleter puede entonces utilizar la búsqueda binaria en lugar de la búsqueda lineal. La búsqueda binaria solo funciona cuando filterMode es Qt::MatchStartsWith.

El modelo puede ser un « list model », un « table model » o un « tree model ». La finalización en modelos de árbol es algo más compleja y se trata en la sección « Handling Tree Models » más adelante.

El completionMode() determina el modo utilizado para ofrecer sugerencias al usuario.

Iteración a través de las sugerencias

Para recuperar una sola cadena candidata, llama a ` setCompletionPrefix()` con el texto que se debe completar y llama a ` currentCompletion()`. Puedes recorrer la lista de sugerencias como se indica a continuación:

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

completionCount() devuelve el número total de completaciones para el prefijo actual. Se debe evitar el uso de ` completionCount()` siempre que sea posible, ya que requiere un escaneo de todo el modelo.

El modelo de autocompletado

completionModel() devuelve un modelo de lista que contiene todas las completaciones posibles para el prefijo de completación actual, en el orden en que aparecen en el modelo. Este modelo se puede utilizar para mostrar las completaciones actuales en una vista personalizada. Al llamar a setCompletionPrefix() se actualiza automáticamente el modelo de completación.

Manejo de modelos de árbol

QCompleter puede buscar completaciones en modelos de árbol, partiendo de la base de que cualquier elemento (o subelemento o sub-subelemento) puede representarse de forma inequívoca como una cadena especificando la ruta de acceso al elemento. La completación se realiza entonces nivel por nivel.

Tomemos el ejemplo de un usuario que escribe una ruta del sistema de archivos. El modelo es un ` QFileSystemModel` (jerárquico). La autocompletación se produce para cada elemento de la ruta. Por ejemplo, si el texto actual es « C:\Wind », QCompleter podría sugerir « Windows » para completar el elemento actual de la ruta. Del mismo modo, si el texto actual es « C:\Windows\Sy », QCompleter podría sugerir « System ».

Para que este tipo de autocompletado funcione, QCompleter debe poder dividir la ruta en una lista de cadenas que coincidan en cada nivel. En el caso de C:\Windows\Sy, debe dividirse en «C:», «Windows» y «Sy». La implementación predeterminada de splitPath() divide completionPrefix utilizando QDir::separator() si el modelo es un QFileSystemModel.

Para proporcionar sugerencias, QCompleter necesita conocer la ruta desde un índice. Esto lo proporciona pathFromIndex(). La implementación predeterminada de pathFromIndex() devuelve los datos de edit role para modelos de lista y la ruta absoluta del archivo si el modo es un QFileSystemModel.

Véase también QAbstractItemModel, QLineEdit, QComboBox y el ejemplo de «Completer».

Documentación sobre tipos de miembros

enum QCompleter::CompletionMode

Esta enumeración especifica cómo se ofrecen las sugerencias al usuario.

ConstanteValorDescripción
QCompleter::PopupCompletion0Las sugerencias actuales se muestran en una ventana emergente.
QCompleter::InlineCompletion2Las sugerencias aparecen en línea (como texto seleccionado).
QCompleter::UnfilteredPopupCompletion1Todas las sugerencias posibles se muestran en una ventana emergente, indicando como «actual» la sugerencia más probable.

Véase también « setCompletionMode » ().

enum QCompleter::ModelSorting

Esta enumeración especifica cómo se ordenan los elementos del modelo.

ConstanteValorDescripción
QCompleter::UnsortedModel0El modelo no está ordenado.
QCompleter::CaseSensitivelySortedModel1El modelo está ordenado distinguiendo entre mayúsculas y minúsculas.
QCompleter::CaseInsensitivelySortedModel2El modelo está ordenado sin distinguir entre mayúsculas y minúsculas.

Véase también setModelSorting().

Documentación de la propiedad

caseSensitivity : Qt::CaseSensitivity

Esta propiedad determina si se tiene en cuenta la distinción entre mayúsculas y minúsculas en la coincidencia

El valor por defecto es « Qt::CaseSensitive ».

Funciones de acceso:

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

Véase también completionColumn, completionRole, modelSorting y filterMode.

completionColumn : int

Esta propiedad indica la columna del modelo en la que se buscan las completaciones.

Si la función « popup()» es una « QListView », se configura automáticamente para mostrar esta columna.

Por defecto, la columna de coincidencia es la 0.

Funciones de acceso:

int completionColumn() const
void setCompletionColumn(int column)

Véase también « completionRole » y « caseSensitivity ».

completionMode : CompletionMode

cómo se muestran las sugerencias al usuario

El valor por defecto es « QCompleter::PopupCompletion ».

Funciones de Access:

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

completionPrefix : QString

Esta propiedad contiene el prefijo de autocompletado que se utiliza para ofrecer sugerencias.

La propiedad ` completionModel()` se actualiza para reflejar la lista de posibles coincidencias para ` prefix`.

Funciones de acceso:

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

completionRole : int

Esta propiedad define el rol del elemento que se utilizará para consultar el contenido de los elementos en busca de coincidencias.

La función predeterminada es « Qt::EditRole ».

Funciones de acceso:

int completionRole() const
void setCompletionRole(int role)

Véase también completionColumn y caseSensitivity.

filterMode : Qt::MatchFlags

Esta propiedad controla cómo se lleva a cabo el filtrado.

Si filterMode se establece en « Qt::MatchStartsWith », solo se mostrarán aquellas entradas que empiecen por los caracteres introducidos. « Qt::MatchContains » mostrará las entradas que contengan los caracteres introducidos, y « Qt::MatchEndsWith » las que terminen por los caracteres introducidos.

Si se establece filterMode en cualquier valor distinto de « Qt::MatchFlag », se mostrará una advertencia y no se realizará ninguna acción. Por este motivo, el indicador « Qt::MatchCaseSensitive » no tiene ningún efecto. Utiliza la propiedad « caseSensitivity » para controlar si se distingue entre mayúsculas y minúsculas.

El modo predeterminado es « Qt::MatchStartsWith ».

Funciones de Access:

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

Véase también caseSensitivity.

maxVisibleItems : int

Esta propiedad indica el tamaño máximo permitido en pantalla del completador, medido en elementos

Por defecto, esta propiedad tiene un valor de 7.

Funciones de acceso:

int maxVisibleItems() const
void setMaxVisibleItems(int maxItems)

modelSorting : ModelSorting

Esta propiedad determina el orden en que se ordena el modelo

Por defecto, no se hace ninguna suposición sobre el orden de los elementos del modelo que proporciona las completaciones.

Si los datos del modelo para completionColumn() y completionRole() están ordenados en orden ascendente, puede establecer esta propiedad en CaseSensitivelySortedModel o CaseInsensitivelySortedModel. En modelos de gran tamaño, esto puede suponer una mejora significativa del rendimiento, ya que el objeto «completer» puede entonces utilizar un algoritmo de búsqueda binaria en lugar de uno lineal.

El orden de clasificación (es decir, ascendente o descendente) del modelo se determina dinámicamente al examinar el contenido del mismo.

Nota: Las mejoras de rendimiento descritas anteriormente no pueden producirse cuando el « caseSensitivity » del «completer» difiere de la distinción entre mayúsculas y minúsculas utilizada por el modelo al ordenar.

Funciones de acceso:

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

Véanse también « setCaseSensitivity()» y « QCompleter::ModelSorting ».

wrapAround : bool

Esta propiedad determina si las sugerencias se reinician al navegar entre elementos

El valor por defecto es «true».

Funciones de Access:

bool wrapAround() const
void setWrapAround(bool wrap)

Documentación de las funciones de miembro

QCompleter::QCompleter(QObject *parent = nullptr)

Crea un objeto « parent » con el « » indicado.

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

Crea un objeto « parent » con el dado, que proporciona sugerencias a partir del model especificado.

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

Crea un objeto QCompleter con el « parent » proporcionado, que utiliza el « list » especificado como fuente de posibles sugerencias.

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

Elimina el objeto «completer».

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

Esta señal se envía cuando el usuario activa un elemento de la función « popup()» (haciendo clic o pulsando la tecla «Intro»). Se proporciona el « index » del elemento en la función « completionModel()».

Nota: Esta señal está sobrecargada. Para conectarse a esta señal:

// Connect using qOverload:
connect(completer, qOverload(&QCompleter::activated),
        receiver, &ReceiverClass::slot);

// Or using a lambda:
connect(completer, qOverload(&QCompleter::activated),
        this, [](const QModelIndex &index) { /* handle activated */ });
Para ver más ejemplos y métodos, consulta «Conexión a señales sobrecargadas».

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

Esta señal se envía cuando el usuario activa un elemento de la lista « popup » () (haciendo clic o pulsando la tecla Intro). Se indica el « text » del elemento.

Nota: Esta señal está sobrecargada. Para conectarse a esta señal:

// Connect using qOverload:
connect(completer, qOverload(&QCompleter::activated),
        receiver, &ReceiverClass::slot);

// Or using a lambda:
connect(completer, qOverload(&QCompleter::activated),
        this, [](const QString &text) { /* handle activated */ });
Para ver más ejemplos y métodos, consulta la sección «Conectarse a señales sobrecargadas».

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

En los modos « QCompleter::PopupCompletion » y «QCompletion::UnfilteredPopupCompletion», al llamar a esta función se muestra la ventana emergente con las sugerencias actuales. Por defecto, si no se especifica « rect », la ventana emergente se muestra en la parte inferior del « widget()». Si se especifica « rect », la ventana emergente se muestra en el borde izquierdo del rectángulo.

En el modo « QCompleter::InlineCompletion », se dispara la señal « highlighted()» con la sugerencia actual.

int QCompleter::completionCount() const

Devuelve el número de sugerencias para el prefijo actual. En el caso de un modelo sin ordenar con un gran número de elementos, esta operación puede resultar costosa. Utiliza setCurrentRow() y currentCompletion() para recorrer todas las sugerencias.

QAbstractItemModel *QCompleter::completionModel() const

Devuelve el modelo de autocompletado. El modelo de autocompletado es un modelo de lista de solo lectura que contiene todas las coincidencias posibles para el prefijo de autocompletado actual. El modelo de autocompletado se actualiza automáticamente para reflejar los autocompletados actuales.

Nota: El valor de retorno de esta función se define como un ` QAbstractItemModel ` únicamente por motivos de generalidad. El tipo real del modelo devuelto es una instancia de una subclase de ` QAbstractProxyModel `.

Véase también completionPrefix y model().

QString QCompleter::currentCompletion() const

Devuelve la cadena de finalización actual. Esto incluye el ` completionPrefix`. Cuando se utiliza junto con ` setCurrentRow()` (), permite recorrer todas las coincidencias.

Véase también setCurrentRow() y currentIndex().

QModelIndex QCompleter::currentIndex() const

Devuelve el índice del modelo de la finalización actual en la función completionModel().

Véanse también setCurrentRow(), currentCompletion() y model().

int QCompleter::currentRow() const

Devuelve la fila actual.

Véase también ` setCurrentRow()`.

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

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

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

Reimplementa: ` QObject::eventFilter` (`QObject *watched`, `QEvent *event`).

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

Esta señal se envía cuando el usuario resalta un elemento en ` popup()`. También se envía si se llama a ` complete()` con ` completionMode()` establecido en ` QCompleter::InlineCompletion`. Se proporciona el ` index ` del elemento en ` completionModel()`.

Nota: Esta señal está sobrecargada. Para conectarse a esta señal:

// Connect using qOverload:
connect(completer, qOverload(&QCompleter::highlighted),
        receiver, &ReceiverClass::slot);

// Or using a lambda:
connect(completer, qOverload(&QCompleter::highlighted),
        this, [](const QModelIndex &index) { /* handle highlighted */ });
Para ver más ejemplos y métodos, consulta «Conexión a señales sobrecargadas».

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

Esta señal se envía cuando el usuario selecciona un elemento de la propiedad « popup()». También se envía si se llama a « complete()» con la propiedad « completionMode()» establecida en « QCompleter::InlineCompletion ». Se proporciona la propiedad « text » del elemento.

Nota: Esta señal está sobrecargada. Para conectarse a esta señal:

// Connect using qOverload:
connect(completer, qOverload(&QCompleter::highlighted),
        receiver, &ReceiverClass::slot);

// Or using a lambda:
connect(completer, qOverload(&QCompleter::highlighted),
        this, [](const QString &text) { /* handle highlighted */ });
Para ver más ejemplos y métodos, consulta «Conexión a señales sobrecargadas».

QAbstractItemModel *QCompleter::model() const

Devuelve el modelo que proporciona cadenas de autocompletado.

Véase también setModel() y completionModel().

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

Devuelve la ruta del elemento index especificado. El objeto de autocompletado utiliza esta información para obtener el texto de autocompletado del modelo subyacente.

La implementación por defecto devuelve el edit role del elemento para los modelos de lista. Devuelve la ruta absoluta del archivo si el modelo es un QFileSystemModel.

Véase también ` splitPath()`.

Devuelve la ventana emergente que se utiliza para mostrar las sugerencias.

Véase también setPopup().

bool QCompleter::setCurrentRow(int row)

Establece la fila actual en el valor especificado por ` row `. Devuelve ` true ` si se realiza correctamente; en caso contrario, devuelve ` false`.

Esta función puede utilizarse junto con currentCompletion() para recorrer todas las completaciones posibles.

Véase también currentRow(), currentCompletion() y completionCount().

void QCompleter::setModel(QAbstractItemModel *model)

Establece el modelo que proporciona sugerencias a model. El model puede ser un modelo de lista o un modelo de árbol. Si ya se ha establecido previamente un modelo y tiene a QCompleter como padre, se elimina.

Por comodidad, si model es un QFileSystemModel, QCompleter cambia su caseSensitivity a Qt::CaseInsensitive en Windows y a Qt::CaseSensitive en otras plataformas.

Véase también completionModel(), modelSorting y Handling Tree Models.

void QCompleter::setPopup(QAbstractItemView *popup)

Establece la ventana emergente utilizada para mostrar las sugerencias en ` popup`. ` QCompleter ` asume la propiedad de la vista.

Se crea automáticamente un ` QListView ` cuando se establece ` completionMode()` en ` QCompleter::PopupCompletion ` o ` QCompleter::UnfilteredPopupCompletion`. La ventana emergente por defecto muestra ` completionColumn()`.

Asegúrate de que esta función se llame antes de modificar la configuración de la vista. Esto es necesario, ya que las propiedades de la vista pueden requerir que se haya establecido un modelo en la vista (por ejemplo, para ocultar columnas en la vista es necesario establecer un modelo en la vista).

Véase también popup().

void QCompleter::setWidget(QWidget *widget)

Establece el widget para el que se proporcionan sugerencias en widget. Esta función se invoca automáticamente cuando se establece un « QCompleter » en un « QLineEdit » mediante QLineEdit::setCompleter() o en un « QComboBox » mediante QComboBox::setCompleter(). El widget debe establecerse explícitamente cuando se proporcionan sugerencias para widgets personalizados.

Véase también widget(), setModel() y setPopup().

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

Divide la ruta del sistema de archivos ( path ) proporcionada en cadenas que se utilizan para realizar la coincidencia en cada nivel en la función ` model()`.

La implementación predeterminada de splitPath() divide una ruta del sistema de archivos basándose en QDir::separator() cuando sourceModel() es un QFileSystemModel.

Cuando se utiliza con modelos de lista, se emplea el primer elemento de la lista devuelta para la coincidencia.

Véanse también pathFromIndex() y Handling Tree Models.

QWidget *QCompleter::widget() const

Devuelve el widget para el que el objeto «completer» proporciona sugerencias.

Véase también setWidget().

© 2026 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.