Libreta de direcciones
El ejemplo de la libreta de direcciones muestra cómo utilizar modelos proxy para mostrar diferentes vistas de los datos a partir de un único modelo.

Este ejemplo ofrece una libreta de direcciones que permite agrupar los contactos alfabéticamente en nueve grupos: ABC, DEF, GHI, …, VW, …, XYZ. Esto se consigue utilizando varias vistas del mismo modelo, cada una de las cuales se filtra mediante una instancia de la clase ` QSortFilterProxyModel `.
Descripción general
La agenda de contactos contiene cuatro clases: « MainWindow », « AddressWidget », « NewAddressTab » y « AddDialog ». La clase « MainWindow » utiliza « AddressWidget » como widget central y proporciona los menús « File » y « Tools ».

La clase AddressWidget es una subclase de QTabWidget que se utiliza para manipular las 10 pestañas que se muestran en el ejemplo: las 9 pestañas de grupos alfabéticos y una instancia de NewAddressTab. La clase NewAddressTab es una subclase de QWidget que solo se utiliza cuando la agenda está vacía, solicitando al usuario que añada algunos contactos. AddressWidget también interactúa con una instancia de TableModel para añadir, editar y eliminar entradas de la agenda.
struct Contact Almacena un contacto y proporciona funciones de comparación y serialización a través de QDataStream:
struct Contact
{
private:
Q_GADGET
Q_PROPERTY(QString name MEMBER name)
Q_PROPERTY(QString address MEMBER address)
public:
QString name;
QString address;
friend bool comparesEqual(const Contact &lhs, const Contact &rhs) noexcept
{
return lhs.name == rhs.name && lhs.address == rhs.address;
}
friend Qt::strong_ordering compareThreeWay(const Contact &lhs, const Contact &rhs) noexcept
{
int cmp = lhs.name.compare(rhs.name);
if (cmp == 0)
cmp = lhs.address.compare(rhs.address);
return Qt::compareThreeWay(cmp, 0);
}
Q_DECLARE_STRONGLY_ORDERED(Contact)
};
inline QDataStream &operator<<(QDataStream &stream, const Contact &contact)
{
return stream << contact.name << contact.address;
}
inline QDataStream &operator>>(QDataStream &stream, Contact &contact)
{
return stream >> contact.name >> contact.address;
}TableModel es una subclase de QAbstractTableModel que proporciona la API estándar de modelo/vista para acceder a los datos. Contiene una lista de los contactos añadidos. Sin embargo, estos datos no se muestran en su totalidad en una sola pestaña. En su lugar, se utiliza QTableView para ofrecer nueve vistas diferentes de los mismos datos, según los grupos alfabéticos.
QSortFilterProxyModel es la clase encargada de filtrar los contactos para cada grupo de contactos. Cada modelo proxy utiliza un ` QRegularExpression ` para filtrar los contactos que no pertenecen al grupo alfabético correspondiente. La clase ` AddDialog ` se utiliza para obtener información del usuario para la agenda de contactos. Esta subclase de ` QDialog ` es instanciada por ` NewAddressTab ` para añadir contactos, y por ` AddressWidget ` para añadir y editar contactos.
Definición de la clase AddressWidget
La clase AddressWidget es, técnicamente, la clase principal de este ejemplo, ya que proporciona funciones para añadir, editar y eliminar contactos, así como para guardarlos en un archivo y cargarlos desde uno.
class AddressWidget : public QTabWidget
{
Q_OBJECT
public:
explicit AddressWidget(QWidget *parent = nullptr);
bool readFromFile();
bool writeToFile();
static QString fileName();
public slots:
void showAddEntryDialog();
void addEntry(const Contact &contact);
void editEntry();
void removeEntry();
signals:
void selectionChanged (const QItemSelection &selected);
private:
void setupTabs();
NewAddressTab *newAddressTab;
QList<Contact> contacts;
using Adapter = decltype(QRangeModelAdapter(std::ref(contacts)));
Adapter adapter;
};AddressWidget extends QTabWidget para poder contener 10 pestañas (NewAddressTab y las 9 pestañas de grupos alfabéticos) y también manipula table, el objeto TableModel, proxyModel, el objeto QSortFilterProxyModel que utilizamos para filtrar las entradas, y tableView, el objeto QTableView.
Almacena los contactos en un ` QList ` y utiliza un ` QRangeModelAdapter ` para operar sobre él.
Proporcionamos los valores de los encabezados de fila para struct Contact mediante una especialización de QRangeModel::RowOptions:
template <>
struct QRangeModel::RowOptions<Contact>
{
inline static QVariant headerData(int section, int role);
};
QVariant QRangeModel::RowOptions<Contact>::headerData(int section, int role)
{
if (role == Qt::DisplayRole) {
switch (section) {
case 0:
return AddressWidget::tr("Name");
case 1:
return AddressWidget::tr("Address");
default:
break;
}
}
return {};
}Implementación de la clase `AddressWidget`
El constructor de ` AddressWidget ` acepta un widget padre y crea instancias de ` NewAddressTab`, ` TableModel ` y ` QSortFilterProxyModel`. Se añade el objeto ` NewAddressTab `, que se utiliza para indicar que la agenda está vacía, y el resto de las 9 pestañas se configuran con ` setupTabs()`.
AddressWidget::AddressWidget(QWidget *parent)
: QTabWidget(parent),
newAddressTab(new NewAddressTab(this)),
adapter(std::ref(contacts))
{
connect(newAddressTab, &NewAddressTab::triggered, this, &AddressWidget::showAddEntryDialog);
addTab(newAddressTab, tr("Address Book"));
setupTabs();
}La función setupTabs() se utiliza para configurar las nueve pestañas de grupos alfabéticos, las vistas de tabla y los modelos proxy en AddressWidget. A su vez, cada modelo proxy se configura para filtrar los nombres de los contactos según el grupo alfabético correspondiente utilizando un objeto QRegularExpression que no distingue entre mayúsculas y minúsculas. Las vistas de tabla también se ordenan en orden ascendente utilizando la función sort() del modelo proxy correspondiente.
El selectionMode de cada vista de tabla se establece en QAbstractItemView::SingleSelection y el selectionBehavior se establece en QAbstractItemView::SelectRows, lo que permite al usuario seleccionar todos los elementos de una fila al mismo tiempo. A cada objeto QTableView se le asigna automáticamente un QItemSelectionModel que realiza un seguimiento de los índices seleccionados.
void AddressWidget::setupTabs()
{
const auto groups = { "ABC"_L1, "DEF"_L1, "GHI"_L1, "JKL"_L1, "MNO"_L1, "PQR"_L1,
"STU"_L1, "VW"_L1, "XYZ"_L1 };
for (QLatin1StringView str : groups) {
const auto regExp = QRegularExpression(QLatin1StringView("^[%1].*").arg(str),
QRegularExpression::CaseInsensitiveOption);
auto *proxyModel = new QSortFilterProxyModel(this);
proxyModel->setSourceModel(adapter.model());
proxyModel->setFilterRegularExpression(regExp);
proxyModel->setFilterKeyColumn(0);
auto *tableView = new QTableView;
tableView->setModel(proxyModel);
tableView->setSelectionBehavior(QAbstractItemView::SelectRows);
tableView->horizontalHeader()->setStretchLastSection(true);
tableView->verticalHeader()->hide();
tableView->setEditTriggers(QAbstractItemView::NoEditTriggers);
tableView->setSelectionMode(QAbstractItemView::SingleSelection);
tableView->setSortingEnabled(true);
connect(tableView->selectionModel(), &QItemSelectionModel::selectionChanged,
this, &AddressWidget::selectionChanged);
connect(this, &QTabWidget::currentChanged, this, [this, tableView](int tabIndex) {
if (widget(tabIndex) == tableView)
emit selectionChanged(tableView->selectionModel()->selection());
});
addTab(tableView, str);
}
}La clase QItemSelectionModel proporciona una señal selectionChanged que está conectada a la señal selectionChanged() de AddressWidget. También conectamos la señal QTabWidget::currentChanged() a la expresión lambda que emite selectionChanged() de AddressWidget. Estas conexiones son necesarias para habilitar las acciones Edit Entry... y Remove Entry en el menú Herramientas de MainWindow. Se explica con más detalle en la implementación de MainWindow.
Cada vista de tabla de la libreta de direcciones se añade como una pestaña a QTabWidget con la etiqueta correspondiente, obtenida de la QStringList de los grupos.

Proporcionamos dos funciones de « addEntry() »: una destinada a aceptar la entrada del usuario y otra que realiza la tarea propiamente dicha de añadir nuevas entradas a la agenda. Dividimos la responsabilidad de añadir entradas en dos partes para permitir que « newAddressTab » inserte datos sin tener que mostrar un cuadro de diálogo.
La primera función addEntry() es una ranura conectada a la acción « Add Entry... » del MainWindow. Esta función crea un objeto AddDialog y, a continuación, llama a la segunda función addEntry() para añadir realmente el contacto a table.
void AddressWidget::showAddEntryDialog()
{
AddDialog aDialog(this);
if (aDialog.exec() == QDialog::Accepted)
addEntry(aDialog.contact());
}La validación básica se realiza en la segunda función addEntry() para evitar entradas duplicadas en la agenda. Como se ha mencionado con respecto a TableModel, esta es una de las razones por las que necesitamos el método getter getContacts().
void AddressWidget::addEntry(const Contact &contact)
{
if (contacts.contains(contact)) {
QMessageBox::information(this, tr("Duplicate Name"),
tr("The name \"%1\" already exists.").arg(contact.name));
return;
}
adapter.insertRow(adapter.rowCount(), contact);
removeTab(indexOf(newAddressTab));
const QChar firstChar = contact.name.at(0).toUpper();
for (int t = 0, tabCount = count(); t < tabCount; ++t) {
if (tabText(t).contains(firstChar)) {
setCurrentIndex(t);
break;
}
}
}Si el modelo aún no contiene una entrada con el mismo nombre, llamamos a setData() para insertar el nombre y la dirección en la primera y segunda columnas. De lo contrario, mostramos un QMessageBox para informar al usuario.
Nota: El enlace « newAddressTab » se elimina una vez que se añade un contacto, ya que la agenda ya no está vacía.
La edición de una entrada permite actualizar únicamente la dirección del contacto, ya que el ejemplo no permite al usuario cambiar el nombre de un contacto existente.
En primer lugar, obtenemos el objeto ` QTableView ` de la pestaña activa mediante ` QTabWidget::currentWidget()`. A continuación, extraemos el ` selectionModel ` del ` tableView ` para obtener los índices seleccionados.
void AddressWidget::editEntry()
{
auto *tableView = static_cast<QTableView *>(currentWidget());
auto *proxy = static_cast<QSortFilterProxyModel *>(tableView->model());
QItemSelectionModel *selectionModel = tableView->selectionModel();
const QModelIndexList indexes = selectionModel->selectedRows();
if (indexes.isEmpty())
return;
const int row = proxy->mapToSource(indexes.constFirst()).row();
const Contact contact = contacts.at(row);A continuación, extraemos los datos de la fila que el usuario desea editar. Estos datos se muestran en una instancia de ` AddDialog ` con un título de ventana diferente. El objeto ` table ` solo se actualiza si se han realizado cambios en los datos de ` aDialog`.
AddDialog aDialog(this);
aDialog.setWindowTitle(tr("Edit a Contact"));
aDialog.editAddress(contact);
if (aDialog.exec() == QDialog::Accepted) {
const Contact newContact = aDialog.contact();
if (newContact != contact)
adapter[row] = newContact;
}
}
Las entradas se eliminan mediante la función removeEntry(). La fila seleccionada se elimina accediendo a ella a través del objeto QItemSelectionModel, selectionModel. El newAddressTab se vuelve a añadir a la AddressWidget solo si el usuario elimina todos los contactos de la agenda.
void AddressWidget::removeEntry()
{
auto *tableView = static_cast<QTableView *>(currentWidget());
auto *proxy = static_cast<QSortFilterProxyModel *>(tableView->model());
QItemSelectionModel *selectionModel = tableView->selectionModel();
const QModelIndexList indexes = selectionModel->selectedRows();
if (indexes.isEmpty())
return;
const int row = proxy->mapToSource(indexes.constFirst()).row();
adapter.removeRow(row);
if (adapter.rowCount() == 0)
insertTab(0, newAddressTab, tr("Address Book"));
}La función « writeToFile() » se utiliza para guardar un archivo que contiene todos los contactos de la agenda. El archivo se guarda en un formato personalizado .dat. El contenido de la lista de contactos se guarda en file mediante QDataStream. Si no se puede abrir el archivo, aparece un QMessageBox con el mensaje de error correspondiente.
bool AddressWidget::writeToFile()
{
QFile file(fileName());
if (!file.open(QIODevice::WriteOnly)) {
QMessageBox::information(this, tr("Unable to open file"),
tr("Cannot write to %1: %2").arg(QDir::toNativeSeparators(fileName()),
file.errorString()));
return false;
}
auto sortedContacts = contacts;
std::sort(sortedContacts.begin(), sortedContacts.end());
QDataStream out(&file);
out << sortedContacts;
return true;
}La función ` readFromFile() ` carga un archivo que contiene todos los contactos de la libreta de direcciones, guardado previamente mediante ` writeToFile()`. Se utiliza ` QDataStream ` para leer el contenido de un archivo ` .dat ` en una lista de contactos y cada uno de ellos se añade mediante ` addEntry()`.
bool AddressWidget::readFromFile()
{
QFile file(fileName());
if (!file.open(QIODevice::ReadOnly)) {
QMessageBox::information(this, tr("Unable to open file"),
tr("Cannot open %1: %2").arg(QDir::toNativeSeparators(fileName()),
file.errorString()));
return false;
}
QList<Contact> contactsIn;
QDataStream in(&file);
in >> contactsIn;
if (contactsIn.isEmpty()) {
QMessageBox::information(this, tr("No contacts in file"),
tr("The file you are attempting to open contains no contacts."));
}
for (const auto &contact : std::as_const(contactsIn))
addEntry(contact);
return true;
}Definición de la clase NewAddressTab
La clase NewAddressTab proporciona una pestaña informativa que indica al usuario que la agenda está vacía. Aparece y desaparece en función del contenido de la agenda, tal y como se menciona en la implementación de AddressWidget.

La clase ` NewAddressTab ` hereda de ` QWidget ` y contiene un ` QLabel ` y un ` QPushButton`.
class NewAddressTab : public QWidget
{
Q_OBJECT
public:
explicit NewAddressTab(QWidget *parent = nullptr);
signals:
void triggered();
};Implementación de la clase `NewAddressTab`
El constructor crea instancias de ` addButton` y ` descriptionLabel `, y conecta la señal de ` addButton` a la señal de ` triggered() `.
NewAddressTab::NewAddressTab(QWidget *parent)
: QWidget(parent)
{
auto *descriptionLabel = new QLabel(tr("There are currently no contacts in your address book. "
"\nClick Add to add new contacts."));
auto *addButton = new QPushButton(tr("Add"));
connect(addButton, &QAbstractButton::clicked, this, &NewAddressTab::triggered);
auto *mainLayout = new QVBoxLayout(this);
mainLayout->addWidget(descriptionLabel, 0, Qt::AlignCenter);
mainLayout->addWidget(addButton, 0, Qt::AlignCenter);
}
Definición de la clase AddDialog
La clase « AddDialog » hereda de « QDialog » y proporciona al usuario un « QLineEdit » y un « QTextEdit » para introducir datos en la agenda de direcciones.
class AddDialog : public QDialog
{
Q_OBJECT
public:
explicit AddDialog(QWidget *parent = nullptr);
Contact contact() const;
void setContact(const Contact &c);
void editAddress(const Contact &c);
private slots:
void updateEnabled();
private:
QDialogButtonBox *buttonBox;
QLineEdit *nameText;
QPlainTextEdit *addressText;
};
Implementación de la clase AddDialog
El constructor de ` AddDialog` configura la interfaz de usuario, creando los widgets necesarios y colocándolos en los diseños.
AddDialog::AddDialog(QWidget *parent)
: QDialog(parent),
buttonBox(new QDialogButtonBox(QDialogButtonBox::Ok | QDialogButtonBox::Cancel, Qt::Horizontal, this)),
nameText(new QLineEdit),
addressText(new QPlainTextEdit)
{
auto *formLayout = new QFormLayout;
formLayout->addRow(tr("Name"), nameText);
formLayout->addRow(tr("Address"), addressText);
auto *mainLayout = new QVBoxLayout(this);
mainLayout->addLayout(formLayout);
mainLayout->addWidget(buttonBox);
connect(buttonBox, &QDialogButtonBox::accepted, this, &QDialog::accept);
connect(buttonBox, &QDialogButtonBox::rejected, this, &QDialog::reject);
connect(nameText, &QLineEdit::textChanged, this, &AddDialog::updateEnabled);
connect(addressText, &QPlainTextEdit::textChanged, this, &AddDialog::updateEnabled);
setWindowTitle(tr("Add a Contact"));
updateEnabled();
}
void AddDialog::updateEnabled()
{
Contact c = contact();
const bool valid = !c.name.isEmpty() && c.name.front().isLetter() && !c.address.isEmpty();
buttonBox->button(QDialogButtonBox::Ok)->setEnabled(valid);
}
Contact AddDialog::contact() const
{
return { nameText->text().trimmed(), addressText->toPlainText().trimmed() };
}
void AddDialog::setContact(const Contact &c)
{
nameText->setText(c.name);
addressText->setPlainText(c.address);
updateEnabled();
}
void AddDialog::editAddress(const Contact &c)
{
nameText->setReadOnly(true);
setContact(c);
}Para dotar al cuadro de diálogo del comportamiento deseado, conectamos los botones « OK » y « Cancel » a las ranuras « accept()» y « reject()» del cuadro de diálogo. Dado que el cuadro de diálogo solo actúa como contenedor de información de nombres y direcciones, no es necesario implementar ninguna otra función para él.
Definición de la clase MainWindow
La clase ` MainWindow ` hereda de ` QMainWindow ` e implementa los menús y las acciones necesarias para gestionar la agenda de direcciones.
![]() | ![]() |
class MainWindow : public QMainWindow
{
Q_OBJECT
public:
MainWindow();
private slots:
void updateActions(const QItemSelection &selection);
void openFile();
void saveFile();
private:
void createMenus();
AddressWidget *addressWidget;
QAction *editAct;
QAction *removeAct;
};La clase ` MainWindow ` utiliza un ` AddressWidget ` como widget central y proporciona el menú «Archivo» con las acciones « Open », « Close » y « Exit », así como el menú « Tools » con las acciones « Add Entry... », « Edit Entry... » y « Remove Entry ».
Implementación de la clase MainWindow
El constructor de MainWindow crea una instancia de AddressWidget, lo establece como su widget central y llama a la función createMenus().
MainWindow::MainWindow()
: QMainWindow(),
addressWidget(new AddressWidget)
{
setCentralWidget(addressWidget);
createMenus();
setWindowTitle(tr("Address Book"));
}La función ` createMenus() ` configura los menús ` File ` y ` Tools `, conectando las acciones a sus respectivas ranuras. Tanto la acción ` Edit Entry... ` como la acción ` Remove Entry ` están desactivadas por defecto, ya que dichas acciones no pueden llevarse a cabo en una agenda vacía. Solo se activan cuando se añaden uno o más contactos.
void MainWindow::createMenus()
{
QMenu *fileMenu = menuBar()->addMenu(tr("&File"));
auto *openAct = new QAction(QIcon::fromTheme(QIcon::ThemeIcon::DocumentOpen),
tr("&Open..."), this);
openAct->setShortcut(QKeySequence(QKeySequence::Open));
fileMenu->addAction(openAct);
connect(openAct, &QAction::triggered, this, &MainWindow::openFile);
...
editAct = new QAction(tr("&Edit Entry..."), this);
editAct->setEnabled(false);
toolMenu->addAction(editAct);
connect(editAct, &QAction::triggered, addressWidget, &AddressWidget::editEntry);
toolMenu->addSeparator();
removeAct = new QAction(tr("&Remove Entry"), this);
removeAct->setEnabled(false);
toolMenu->addAction(removeAct);
connect(removeAct, &QAction::triggered, addressWidget, &AddressWidget::removeEntry);
connect(addressWidget, &AddressWidget::selectionChanged,
this, &MainWindow::updateActions);
}Además de conectar todas las señales de las acciones a sus respectivas ranuras, también conectamos la señal selectionChanged() de AddressWidget a su ranura updateActions().
La función « openFile() » abre un archivo « addressbook.dat » personalizado que contiene los contactos de la libreta de direcciones. Esta función es un slot conectado a « openAct » en el menú « File ».
void MainWindow::openFile()
{
if (addressWidget->readFromFile())
statusBar()->showMessage(tr("Read %1").arg(QDir::toNativeSeparators(AddressWidget::fileName())));
}La función « saveFile() » guarda un archivo addressbook.dat personalizado que contendrá los contactos de la agenda. Esta función es una ranura conectada a « saveAct » en el menú « File ».
void MainWindow::saveFile()
{
if (addressWidget->writeToFile())
statusBar()->showMessage(tr("Wrote %1").arg(QDir::toNativeSeparators(AddressWidget::fileName())));
}La función « updateActions() » activa y desactiva « Edit Entry... » y « Remove Entry » en función del contenido de la agenda de contactos. Si la agenda está vacía, estas acciones se desactivan; en caso contrario, se activan. Esta función es una ranura conectada a la señal « selectionChanged() » de « AddressWidget ».
void MainWindow::updateActions(const QItemSelection &selection)
{
const QModelIndexList indexes = selection.indexes();
removeAct->setEnabled(!indexes.isEmpty());
editAct->setEnabled(!indexes.isEmpty());
}Función main()
La función principal de la agenda crea una instancia de ` QApplication ` y abre un ` MainWindow ` antes de ejecutar el bucle de eventos.
int main(int argc, char *argv[])
{
QApplication app(argc, argv);
MainWindow mw;
const auto availableGeometry = mw.screen()->availableGeometry();
mw.resize(availableGeometry.width() / 3, availableGeometry.height() / 3);
mw.show();
return QApplication::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.

