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.
| Constante | Valor | Descripción |
|---|---|---|
QCompleter::PopupCompletion | 0 | Las sugerencias actuales se muestran en una ventana emergente. |
QCompleter::InlineCompletion | 2 | Las sugerencias aparecen en línea (como texto seleccionado). |
QCompleter::UnfilteredPopupCompletion | 1 | Todas 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.
| Constante | Valor | Descripción |
|---|---|---|
QCompleter::UnsortedModel | 0 | El modelo no está ordenado. |
QCompleter::CaseSensitivelySortedModel | 1 | El modelo está ordenado distinguiendo entre mayúsculas y minúsculas. |
QCompleter::CaseInsensitivelySortedModel | 2 | El 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 */ }); [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 */ }); [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 */ }); [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 */ }); 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()`.
QAbstractItemView *QCompleter::popup() const
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.