Ejemplo de Completer
El ejemplo «Completer» muestra cómo proporcionar funciones de autocompletado de cadenas para un widget de entrada basándose en los datos proporcionados por un modelo.

Este ejemplo utiliza un modelo de elementos personalizado, FileSystemModel, y un objeto QCompleter. QCompleter es una clase que proporciona sugerencias basadas en un modelo de elementos. El tipo de modelo, el modo de autocompletado y la distinción entre mayúsculas y minúsculas se pueden seleccionar mediante cuadros combinados.
El archivo de recursos
El ejemplo Completer requiere un archivo de recursos para almacenar los archivos countries.txt y words.txt. El archivo de recursos contiene el siguiente código:
<!DOCTYPE RCC><RCC version="1.0">
<qresource prefix="/">
<file>resources/countries.txt</file>
<file>resources/wordlist.txt</file>
</qresource>
</RCC>Definición de la clase `FileSystemModel`
La clase ` FileSystemModel ` es una subclase de ` QFileSystemModel`, que proporciona un modelo de datos para el sistema de archivos local.
class FileSystemModel : public QFileSystemModel
{
public:
FileSystemModel(QObject *parent = nullptr);
QVariant data(const QModelIndex &index, int role = Qt::DisplayRole) const override;
};Esta clase solo tiene un constructor y una función « data() », ya que se ha creado únicamente para permitir que « data() » devuelva la ruta completa del archivo para la función de visualización, a diferencia de la función « data() » de « QFileSystemModel », que solo devuelve la carpeta y no la etiqueta de la unidad. Esto se explica con más detalle en la implementación de « FileSystemModel ».
Implementación de la clase `FileSystemModel`
El constructor de la clase ` FileSystemModel ` se utiliza para pasar ` parent ` a ` QFileSystemModel`.
FileSystemModel::FileSystemModel(QObject *parent)
: QFileSystemModel(parent)
{
}Como se ha mencionado anteriormente, la función ` data() ` se reimplementa para que devuelva la ruta completa del archivo con fines de visualización. Por ejemplo, con ` QFileSystemModel`, se verá «Program Files» en la vista. Sin embargo, con ` FileSystemModel`, se verá «C:\Program Files».
QVariant FileSystemModel::data(const QModelIndex &index, int role) const
{
if (role == Qt::DisplayRole && index.column() == 0) {
QString path = QDir::toNativeSeparators(filePath(index));
if (path.endsWith(QDir::separator()))
path.chop(1);
return path;
}
return QFileSystemModel::data(index, role);
}El método ` Qt::EditRole`, que utiliza ` QCompleter ` para buscar coincidencias, no se modifica.
Definición de la clase MainWindow
La clase « MainWindow » es una subclase de « QMainWindow » e implementa cinco slots privados: « about() », « changeCase() », « changeMode() », « changeModel() » y « changeMaxVisible() ».
class MainWindow : public QMainWindow
{
Q_OBJECT
public:
MainWindow(QWidget *parent = nullptr);
private slots:
void about();
void changeCase(int);
void changeMode(int);
void changeModel();
void changeMaxVisible(int);Dentro de la clase « MainWindow », tenemos dos funciones privadas: « createMenu() » y « modelFromFile() ». También declaramos los widgets privados necesarios: tres objetos « QComboBox », un « QCheckBox », un « QCompleter », un « QLabel » y un « QLineEdit ».
private:
void createMenu();
QAbstractItemModel *modelFromFile(const QString &fileName);
QComboBox *caseCombo = nullptr;
QComboBox *modeCombo = nullptr;
QComboBox *modelCombo = nullptr;
QSpinBox *maxVisibleSpinBox = nullptr;
QCheckBox *wrapCheckBox = nullptr;
QCompleter *completer = nullptr;
QLabel *contentsLabel = nullptr;
QLineEdit *lineEdit = nullptr;
};Implementación de la clase MainWindow
El constructor de ` MainWindow ` crea un ` MainWindow ` con un widget padre e inicializa los miembros privados. A continuación, se invoca la función ` createMenu() `.
Configuramos tres objetos ` QComboBox `: ` modelComb`, ` modeCombo ` y ` caseCombo`. Por defecto, el ` modelCombo ` está establecido en ` QFileSystemModel`, el ` modeCombo ` en «Filtered Popup» y el ` caseCombo ` en «Case Insensitive».
MainWindow::MainWindow(QWidget *parent)
: QMainWindow(parent)
{
createMenu();
QWidget *centralWidget = new QWidget;
QLabel *modelLabel = new QLabel;
modelLabel->setText(tr("Model"));
modelCombo = new QComboBox;
modelCombo->addItem(tr("QFileSystemModel"));
modelCombo->addItem(tr("QFileSystemModel that shows full path"));
modelCombo->addItem(tr("Country list"));
modelCombo->addItem(tr("Word list"));
modelCombo->setCurrentIndex(0);
QLabel *modeLabel = new QLabel;
modeLabel->setText(tr("Completion Mode"));
modeCombo = new QComboBox;
modeCombo->addItem(tr("Inline"));
modeCombo->addItem(tr("Filtered Popup"));
modeCombo->addItem(tr("Unfiltered Popup"));
modeCombo->setCurrentIndex(1);
QLabel *caseLabel = new QLabel;
caseLabel->setText(tr("Case Sensitivity"));
caseCombo = new QComboBox;
caseCombo->addItem(tr("Case Insensitive"));
caseCombo->addItem(tr("Case Sensitive"));
caseCombo->setCurrentIndex(0);Se crea el « maxVisibleSpinBox », que determina el número de elementos visibles en el completador
A continuación, se configura el wrapCheckBox. Este checkBox determina si la propiedad setWrapAround() del completer está habilitada o deshabilitada.
QLabel *maxVisibleLabel = new QLabel;
maxVisibleLabel->setText(tr("Max Visible Items"));
maxVisibleSpinBox = new QSpinBox;
maxVisibleSpinBox->setRange(3,25);
maxVisibleSpinBox->setValue(10);
wrapCheckBox = new QCheckBox;
wrapCheckBox->setText(tr("Wrap around completions"));
wrapCheckBox->setChecked(true);Instanciamos ` contentsLabel ` y establecemos su política de tamaño en ` fixed`. A continuación, las señales ` activated()` de los cuadros combinados se conectan a sus respectivas ranuras.
contentsLabel = new QLabel;
contentsLabel->setSizePolicy(QSizePolicy::Fixed, QSizePolicy::Fixed);
connect(modelCombo, &QComboBox::activated,
this, &MainWindow::changeModel);
connect(modeCombo, &QComboBox::activated,
this, &MainWindow::changeMode);
connect(caseCombo, &QComboBox::activated,
this, &MainWindow::changeCase);
connect(maxVisibleSpinBox, &QSpinBox::valueChanged,
this, &MainWindow::changeMaxVisible);Se configura el ` lineEdit ` y, a continuación, organizamos todos los widgets utilizando un ` QGridLayout`. Se llama a la función ` changeModel() ` para inicializar el ` completer`.
lineEdit = new QLineEdit;
QGridLayout *layout = new QGridLayout;
layout->addWidget(modelLabel, 0, 0); layout->addWidget(modelCombo, 0, 1);
layout->addWidget(modeLabel, 1, 0); layout->addWidget(modeCombo, 1, 1);
layout->addWidget(caseLabel, 2, 0); layout->addWidget(caseCombo, 2, 1);
layout->addWidget(maxVisibleLabel, 3, 0); layout->addWidget(maxVisibleSpinBox, 3, 1);
layout->addWidget(wrapCheckBox, 4, 0);
layout->addWidget(contentsLabel, 5, 0, 1, 2);
layout->addWidget(lineEdit, 6, 0, 1, 2);
centralWidget->setLayout(layout);
setCentralWidget(centralWidget);
changeModel();
setWindowTitle(tr("Completer"));
lineEdit->setFocus();
}La función « createMenu() » se utiliza para instanciar los objetos « QAction » necesarios para rellenar « fileMenu » y « helpMenu ». Las señales « triggered()» de las acciones se conectan a sus respectivas ranuras.
void MainWindow::createMenu()
{
QAction *exitAction = new QAction(tr("Exit"), this);
QAction *aboutAct = new QAction(tr("About"), this);
QAction *aboutQtAct = new QAction(tr("About Qt"), this);
connect(exitAction, &QAction::triggered, qApp, &QApplication::quit);
connect(aboutAct, &QAction::triggered, this, &MainWindow::about);
connect(aboutQtAct, &QAction::triggered, qApp, &QApplication::aboutQt);
QMenu *fileMenu = menuBar()->addMenu(tr("File"));
fileMenu->addAction(exitAction);
QMenu *helpMenu = menuBar()->addMenu(tr("About"));
helpMenu->addAction(aboutAct);
helpMenu->addAction(aboutQtAct);
}La función ` modelFromFile() ` acepta el ` fileName ` de un archivo y lo procesa en función de su contenido.
En primer lugar, validamos el file para asegurarnos de que se puede abrir en modo QFile::ReadOnly. Si esto no se consigue, la función devuelve un QStringListModel vacío.
QAbstractItemModel *MainWindow::modelFromFile(const QString &fileName)
{
QFile file(fileName);
if (!file.open(QFile::ReadOnly))
return new QStringListModel(completer);A continuación, se sustituye el cursor del ratón por Qt::WaitCursor antes de rellenar un objeto QStringList, words, con el contenido de file. Una vez hecho esto, se restablece el cursor del ratón.
#ifndef QT_NO_CURSOR
QGuiApplication::setOverrideCursor(QCursor(Qt::WaitCursor));
#endif
QStringList words;
while (!file.atEnd()) {
QByteArray line = file.readLine();
if (!line.isEmpty())
words << QString::fromUtf8(line.trimmed());
}
#ifndef QT_NO_CURSOR
QGuiApplication::restoreOverrideCursor();
#endifComo se ha mencionado anteriormente, el archivo de recursos contiene dos archivos: countries.txt y words.txt. Si el valor leído de ` file ` es `words.txt`, devolvemos un ` QStringListModel ` con ` words ` como su ` QStringList ` y ` completer ` como su `parent`.
if (!fileName.contains(QLatin1String("countries.txt")))
return new QStringListModel(words, completer);Si el archivo file que se lee es countries.txt, entonces necesitamos un QStandardItemModel con words.count() filas, 2 columnas y completer como padre.
QStandardItemModel *m = new QStandardItemModel(words.count(), 2, completer);Una línea estándar en countries.txt es:
Noruega NO
Por lo tanto, para rellenar el objeto ` QStandardItemModel `, ` m`, tenemos que separar el nombre del país y su símbolo. Una vez hecho esto, devolvemos ` m`.
for (int i = 0; i < words.count(); ++i) {
QModelIndex countryIdx = m->index(i, 0);
QModelIndex symbolIdx = m->index(i, 1);
QString country = words.at(i).mid(0, words[i].length() - 2).trimmed();
QString symbol = words.at(i).right(2);
m->setData(countryIdx, country);
m->setData(symbolIdx, symbol);
}
return m;
}La función ` changeMode() ` establece el modo de ` completer`, en función del valor de ` index`.
void MainWindow::changeMode(int index)
{
QCompleter::CompletionMode mode;
if (index == 0)
mode = QCompleter::InlineCompletion;
else if (index == 1)
mode = QCompleter::PopupCompletion;
else
mode = QCompleter::UnfilteredPopupCompletion;
completer->setCompletionMode(mode);
}La función ` changeModel() ` cambia el modelo de elemento utilizado en función del modelo seleccionado por el usuario.
Se utiliza una instrucción « switch » para cambiar el modelo de elemento en función del índice de « modelCombo ». Si « case » es 0, utilizamos un « QFileSystemModel » sin ordenar, lo que nos proporciona una ruta de archivo que excluye la etiqueta de la unidad.
void MainWindow::changeModel()
{
delete completer;
completer = new QCompleter(this);
completer->setMaxVisibleItems(maxVisibleSpinBox->value());
switch (modelCombo->currentIndex()) {
default:
case 0:
{ // Unsorted QFileSystemModel
QFileSystemModel *fsModel = new QFileSystemModel(completer);
fsModel->setRootPath(QString());
completer->setModel(fsModel);
contentsLabel->setText(tr("Enter file path"));
}
break;Tenga en cuenta que creamos el modelo con completer como padre, ya que esto nos permite sustituir el modelo por uno nuevo. El completer garantizará que el antiguo se elimine en el momento en que se le asigne un nuevo modelo.
Si case es 1, utilizamos el DirModel que hemos definido anteriormente, lo que da como resultado rutas completas para los archivos.
case 1:
{ // FileSystemModel that shows full paths
FileSystemModel *fsModel = new FileSystemModel(completer);
completer->setModel(fsModel);
fsModel->setRootPath(QString());
contentsLabel->setText(tr("Enter file path"));
}
break;Cuando case es 2, intentamos autocompletar los nombres de los países. Para ello se requiere un objeto QTreeView, treeView. Los nombres de los países se extraen de countries.txt y se configura la ventana emergente utilizada para mostrar las sugerencias en treeView.
case 2:
{ // Country List
completer->setModel(modelFromFile(":/resources/countries.txt"));
QTreeView *treeView = new QTreeView;
completer->setPopup(treeView);
treeView->setRootIsDecorated(false);
treeView->header()->hide();
treeView->header()->setStretchLastSection(false);
treeView->header()->setSectionResizeMode(0, QHeaderView::Stretch);
treeView->header()->setSectionResizeMode(1, QHeaderView::ResizeToContents);
contentsLabel->setText(tr("Enter name of your country"));
}
break;La siguiente captura de pantalla muestra el Completer con el modelo de lista de países.

Si el valor de « case » es 3, intentamos autocompletar palabras. Esto se hace utilizando un objeto « QStringListModel » que contiene datos extraídos del archivo «words.txt». El modelo está ordenado case insensitively.
La siguiente captura de pantalla muestra el «Completer» con el modelo de lista de palabras.

Una vez seleccionado el tipo de modelo, llamamos a las funciones « changeMode() » y « changeCase() », y configuramos la opción «wrap» en consecuencia. La señal « clicked()» de « wrapCheckBox » se conecta a la ranura « setWrapAround()» de « completer ».
case 3:
{ // Word list
completer->setModel(modelFromFile(":/resources/wordlist.txt"));
completer->setModelSorting(QCompleter::CaseInsensitivelySortedModel);
contentsLabel->setText(tr("Enter a word"));
}
break;
}
changeMode(modeCombo->currentIndex());
changeCase(caseCombo->currentIndex());
completer->setWrapAround(wrapCheckBox->isChecked());
lineEdit->setCompleter(completer);
connect(wrapCheckBox, &QAbstractButton::clicked, completer, &QCompleter::setWrapAround);
}La variable ` changeMaxVisible() ` actualiza el número máximo de elementos visibles en el completador.
void MainWindow::changeMaxVisible(int max)
{
completer->setMaxVisibleItems(max);
}La función « about() » ofrece una breve descripción del ejemplo.
void MainWindow::about()
{
QMessageBox::about(this, tr("About"), tr("This example demonstrates the "
"different features of the QCompleter class."));
}main() Función
La función « main() » crea instancias de « QApplication » y « MainWindow » e invoca la función « show()».
int main(int argc, char *argv[])
{
QApplication app(argc, argv);
MainWindow window;
window.show();
return app.exec();
}© 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.