En esta página

Ejemplo de marcadores de QXmlStream

Muestra cómo leer y escribir archivos XBEL.

El ejemplo de marcadores de QXmlStream proporciona un visor para archivos XML Bookmark Exchange Language (XBEL). Puede leer marcadores utilizando el ` QXmlStreamReader ` de Qt y volver a escribirlos utilizando ` QXmlStreamWriter`. Dado que este ejemplo tiene como objetivo mostrar cómo utilizar estos tipos de lectura y escritura, no ofrece ninguna forma de abrir un marcador, añadir uno nuevo o fusionar dos archivos de marcadores, y solo ofrece un alcance mínimo para la edición de marcadores. No obstante, sin duda podría ampliarse con dichas características, si así se desea.

Árbol de marcadores con las columnas «Título» y «Ubicación»

Definición de la clase XbelWriter

La clase ` XbelWriter ` toma un ` tree widget ` que describe una jerarquía de carpetas que contienen marcadores. Su método ` writeFile() ` proporciona los medios para escribir esta jerarquía, en formato XBEL, en un dispositivo de salida determinado.

Internamente, registra el widget de árbol que se le ha proporcionado y empaqueta una instancia privada de ` QXmlStreamWriter`, que le proporciona los medios para transmitir XML. Cuenta con un ` writeItem() ` interno para escribir cada elemento de su árbol.

class XbelWriter
{
public:
    explicit XbelWriter(const QTreeWidget *treeWidget);
    bool writeFile(QIODevice *device);

private:
    void writeItem(const QTreeWidgetItem *item);
    QXmlStreamWriter xml;
    const QTreeWidget *treeWidget;
};

Implementación de la clase XbelWriter

El constructor de ` XbelWriter ` acepta el ` treeWidget ` que va a describir. Lo almacena y activa la propiedad de formato automático de ` QXmlStreamWriter`. Esta última divide los datos en varias líneas, con sangría para indicar la estructura del árbol, lo que facilita la lectura de la salida XML.

XbelWriter::XbelWriter(const QTreeWidget *treeWidget) : treeWidget(treeWidget)
{
    xml.setAutoFormatting(true);
}

La función ` writeFile() ` acepta un objeto ` QIODevice ` y ordena a su miembro ` QXmlStreamWriter ` que escriba en este dispositivo, utilizando ` setDevice()`. A continuación, esta función escribe la definición de tipo de documento (DTD), el elemento inicial y la versión, y delega la escritura de cada uno de los elementos de nivel superior de ` treeWidget` a ` writeItem()`. Por último, cierra el documento y devuelve un valor.

bool XbelWriter::writeFile(QIODevice *device)
{
    xml.setDevice(device);

    xml.writeStartDocument();
    xml.writeDTD("<!DOCTYPE xbel>"_L1);
    xml.writeStartElement("xbel"_L1);
    xml.writeAttribute("version"_L1, "1.0"_L1);
    for (int i = 0; i < treeWidget->topLevelItemCount(); ++i)
        writeItem(treeWidget->topLevelItem(i));

    xml.writeEndDocument();
    return true;
}

La función writeItem() acepta un objeto QTreeWidgetItem y escribe en su flujo XML una representación del objeto, que depende de su UserRole, que puede ser uno de los siguientes: "folder", "bookmark" o "separator". Dentro de cada carpeta, se invoca a sí misma de forma recursiva sobre cada elemento secundario, para incluir de forma recursiva una representación de cada elemento secundario dentro del elemento XML de la carpeta.

void XbelWriter::writeItem(const QTreeWidgetItem *item)
{
    QString tagName = item->data(0, Qt::UserRole).toString();
    if (tagName == "folder"_L1) {
        bool folded = !item->isExpanded();
        xml.writeStartElement(tagName);
        xml.writeAttribute("folded"_L1, folded ? "yes"_L1 : "no"_L1);
        xml.writeTextElement("title"_L1, item->text(0));
        for (int i = 0; i < item->childCount(); ++i)
            writeItem(item->child(i));
        xml.writeEndElement();
    } else if (tagName == "bookmark"_L1) {
        xml.writeStartElement(tagName);
        if (!item->text(1).isEmpty())
            xml.writeAttribute("href"_L1, item->text(1));
        xml.writeTextElement("title"_L1, item->text(0));
        xml.writeEndElement();
    } else if (tagName == "separator"_L1) {
        xml.writeEmptyElement(tagName);
    }
}

Definición de la clase XbelReader

La clase ` XbelReader ` toma un objeto ` tree widget ` para rellenarlo con elementos que describen una jerarquía de marcadores. Admite la lectura de datos XBEL desde un objeto ` QIODevice ` como fuente de dichos elementos. Si falla el análisis de los datos XBEL, puede informar de cuál ha sido el error.

Internamente, registra el ` QTreeWidget ` que va a rellenar y crea una instancia de ` QXmlStreamReader`, la clase complementaria de ` QXmlStreamWriter`, que utilizará para leer los datos XBEL.

class XbelReader
{
public:
    XbelReader(QTreeWidget *treeWidget);

    bool read(QIODevice *device);
    QString errorString() const;

private:
    void readXBEL();
    void readTitle(QTreeWidgetItem *item);
    void readSeparator(QTreeWidgetItem *item);
    void readFolder(QTreeWidgetItem *item);
    void readBookmark(QTreeWidgetItem *item);

    QTreeWidgetItem *createChildItem(QTreeWidgetItem *item);

    QXmlStreamReader xml;
    QTreeWidget *treeWidget;

    QIcon folderIcon;
    QIcon bookmarkIcon;
};

Implementación de la clase XbelReader

Dado que el lector XBEL solo se ocupa de leer elementos XML, hace un uso extensivo de la función de conveniencia readNextStartElement().

El constructor de XbelReader requiere un QTreeWidget que se va a rellenar. Rellena el estilo del widget de árbol con los iconos adecuados: un icono de carpeta que cambia de forma para indicar si cada carpeta está abierta o cerrada; y un icono de archivo estándar para los marcadores individuales dentro de esas carpetas.

XbelReader::XbelReader(QTreeWidget *treeWidget) : treeWidget(treeWidget)
{
    QStyle *style = treeWidget->style();

    folderIcon.addPixmap(style->standardPixmap(QStyle::SP_DirClosedIcon), QIcon::Normal,
                         QIcon::Off);
    folderIcon.addPixmap(style->standardPixmap(QStyle::SP_DirOpenIcon), QIcon::Normal, QIcon::On);
    bookmarkIcon.addPixmap(style->standardPixmap(QStyle::SP_FileIcon));
}

La función ` read() ` acepta un ` QIODevice`. Esta función ordena a su miembro ` QXmlStreamReader ` que lea el contenido de dicho dispositivo. Ten en cuenta que la entrada XML debe estar bien formada para que ` QXmlStreamReader` la acepte. En primer lugar, lee la estructura externa y verifica que el contenido sea un archivo XBEL 1.0; si lo es, ` read() ` delega la lectura real del contenido al ` readXBEL()` interno.

De lo contrario, se utiliza la función raiseError() para registrar un mensaje de error. El propio lector también puede hacer lo mismo si encuentra errores en la entrada. Cuando read() ha terminado, devuelve «true» si no se han producido errores.

bool XbelReader::read(QIODevice *device)
{
    xml.setDevice(device);

    if (xml.readNextStartElement()) {
        if (xml.name() == "xbel"_L1 && xml.attributes().value("version"_L1) == "1.0"_L1)
            readXBEL();
        else
            xml.raiseError(QObject::tr("The file is not an XBEL version 1.0 file."));
    }

    return !xml.error();
}

Si read() devuelve «false», quien la invoca puede obtener una descripción del error, junto con el número de línea y columna dentro del flujo, llamando a la función errorString().

QString XbelReader::errorString() const
{
    return QObject::tr("%1\nLine %2, column %3")
            .arg(xml.errorString())
            .arg(xml.lineNumber())
            .arg(xml.columnNumber());
}

La función ` readXBEL() ` lee el nombre de un `startElement` y llama a la función adecuada para leerlo, dependiendo de si el nombre de la etiqueta es ` "folder"`, ` "bookmark" ` o ` "separator"`. Se omiten todos los demás elementos que se encuentren. La función comienza con una precondición, verificando que el lector de XML acaba de abrir un elemento ` "xbel" `.

void XbelReader::readXBEL()
{
    Q_ASSERT(xml.isStartElement() && xml.name() == "xbel"_L1);

    while (xml.readNextStartElement()) {
        if (xml.name() == "folder"_L1)
            readFolder(nullptr);
        else if (xml.name() == "bookmark"_L1)
            readBookmark(nullptr);
        else if (xml.name() == "separator"_L1)
            readSeparator(nullptr);
        else
            xml.skipCurrentElement();
    }
}

La función ` readBookmark() ` crea un nuevo elemento editable que representa un único marcador. Registra el atributo XML ` "href" ` del elemento actual como texto de la segunda columna del elemento y establece provisionalmente el texto de la primera columna como ` "Unknown title" ` antes de analizar el resto del elemento en busca de un elemento `title` que lo sustituya, omitiendo cualquier elemento secundario no reconocido.

void XbelReader::readTitle(QTreeWidgetItem *item)
{
    Q_ASSERT(xml.isStartElement() && xml.name() == "title"_L1);
    item->setText(0, xml.readElementText());
}

La función « readTitle() » lee el título de un marcador y lo registra como el título (texto de la primera columna) del elemento para el que se ha invocado.

void XbelReader::readSeparator(QTreeWidgetItem *item)
{
    Q_ASSERT(xml.isStartElement() && xml.name() == "separator"_L1);
    constexpr char16_t midDot = u'\xB7';
    static const QString dots(30, midDot);

    QTreeWidgetItem *separator = createChildItem(item);
    separator->setFlags(item ? item->flags() & ~Qt::ItemIsSelectable : Qt::ItemFlags{});
    separator->setText(0, dots);
    xml.skipCurrentElement();
}

La función ` readSeparator() ` crea un separador y establece sus indicadores. El texto del elemento separador se establece en 30 puntos centrados. A continuación, se omite el resto del elemento mediante ` skipCurrentElement()`.

void XbelReader::readSeparator(QTreeWidgetItem *item)
{
    Q_ASSERT(xml.isStartElement() && xml.name() == "separator"_L1);
    constexpr char16_t midDot = u'\xB7';
    static const QString dots(30, midDot);

    QTreeWidgetItem *separator = createChildItem(item);
    separator->setFlags(item ? item->flags() & ~Qt::ItemIsSelectable : Qt::ItemFlags{});
    separator->setText(0, dots);
    xml.skipCurrentElement();
}

La función ` readFolder() ` crea un elemento y recorre el contenido del elemento de carpeta, añadiendo elementos hijos a este elemento para representar el contenido del elemento de carpeta. El bucle sobre el contenido de la carpeta es similar en su forma al de ` readXBEL()`, salvo que ahora acepta un elemento de título para establecer el título de la carpeta.

void XbelReader::readFolder(QTreeWidgetItem *item)
{
    Q_ASSERT(xml.isStartElement() && xml.name() == "folder"_L1);

    QTreeWidgetItem *folder = createChildItem(item);
    bool folded = xml.attributes().value("folded"_L1) != "no"_L1;
    folder->setExpanded(!folded);

    while (xml.readNextStartElement()) {
        if (xml.name() == "title"_L1)
            readTitle(folder);
        else if (xml.name() == "folder"_L1)
            readFolder(folder);
        else if (xml.name() == "bookmark"_L1)
            readBookmark(folder);
        else if (xml.name() == "separator"_L1)
            readSeparator(folder);
        else
            xml.skipCurrentElement();
    }
}

La función auxiliar ` createChildItem() ` crea un nuevo elemento del widget de árbol que es un elemento hijo del elemento dado o, si no se proporciona ningún elemento padre, un elemento hijo directo del widget de árbol. Establece el ` UserRole ` del nuevo elemento en el nombre de la etiqueta del elemento XML actual, de forma análoga a cómo `XbelWriter::writeFile()` utiliza ese ` UserRole`.

QTreeWidgetItem *XbelReader::createChildItem(QTreeWidgetItem *item)
{
    QTreeWidgetItem *childItem = item ? new QTreeWidgetItem(item) : new QTreeWidgetItem(treeWidget);
    childItem->setData(0, Qt::UserRole, xml.name().toString());
    return childItem;
}

Definición de la clase MainWindow

La clase « MainWindow » es una subclase de « QMainWindow », con un menú « File » y un menú « Help ».

class MainWindow : public QMainWindow
{
    Q_OBJECT

public:
    MainWindow();

public slots:
    void open();
    void saveAs();
    void about();
#if QT_CONFIG(clipboard) && QT_CONFIG(contextmenu)
    void onCustomContextMenuRequested(const QPoint &pos);
#endif
private:
    void createMenus();

    QTreeWidget *const treeWidget;
};

Implementación de la clase MainWindow

El constructor de MainWindow configura su objeto QTreeWidget, treeWidget, como su propio widget central, con encabezados de columna para el título y la ubicación de cada marcador. Configura un menú personalizado que permite al usuario realizar acciones sobre marcadores individuales dentro del widget de árbol.

Invoca a ` createMenus() ` para configurar sus propios menús y las acciones correspondientes. Establece su título, indica que está listo y ajusta su tamaño a una proporción razonable del espacio disponible en pantalla.

MainWindow::MainWindow() : treeWidget(new QTreeWidget)
{
    treeWidget->header()->setSectionResizeMode(QHeaderView::Stretch);
    treeWidget->setHeaderLabels(QStringList{tr("Title"), tr("Location")});
#if QT_CONFIG(clipboard) && QT_CONFIG(contextmenu)
    treeWidget->setContextMenuPolicy(Qt::CustomContextMenu);
    connect(treeWidget, &QWidget::customContextMenuRequested,
            this, &MainWindow::onCustomContextMenuRequested);
#endif
    setCentralWidget(treeWidget);

    createMenus();

    statusBar()->showMessage(tr("Ready"));

    setWindowTitle(tr("QXmlStream Bookmarks"));
    const QSize availableSize = screen()->availableGeometry().size();
    resize(availableSize.width() / 2, availableSize.height() / 3);
}

Un menú personalizado, que se activa cuando el usuario hace clic con el botón derecho del ratón sobre un marcador, permite copiar el marcador como enlace o hacer que un navegador de escritorio abra la URL a la que hace referencia. Este menú lo implementa (cuando las funciones pertinentes están habilitadas) onCustomContextMenuRequested().

#if QT_CONFIG(clipboard) && QT_CONFIG(contextmenu)
void MainWindow::onCustomContextMenuRequested(const QPoint &pos)
{
    const QTreeWidgetItem *item = treeWidget->itemAt(pos);
    if (!item)
        return;
    const QString url = item->text(1);
    QMenu contextMenu;
    QAction *copyAction = contextMenu.addAction(tr("Copy Link to Clipboard"));
    QAction *openAction = contextMenu.addAction(tr("Open"));
    QAction *action = contextMenu.exec(treeWidget->viewport()->mapToGlobal(pos));
    if (action == copyAction)
        QGuiApplication::clipboard()->setText(url);
    else if (action == openAction)
        QDesktopServices::openUrl(QUrl(url));
}
#endif // QT_CONFIG(clipboard) && QT_CONFIG(contextmenu)

La función createMenus() crea los objetos fileMenu y helpMenu y les añade objetos QAction, vinculados de diversas formas a las funciones open(), saveAs() y about(), junto con QWidget::close() y QApplication::aboutQt(). Las conexiones son las que se muestran a continuación:

void MainWindow::createMenus()
{
    QMenu *fileMenu = menuBar()->addMenu(tr("&File"));
    QAction *openAct = fileMenu->addAction(tr("&Open..."), this, &MainWindow::open);
    openAct->setShortcuts(QKeySequence::Open);

    QAction *saveAsAct = fileMenu->addAction(tr("&Save As..."), this, &MainWindow::saveAs);
    saveAsAct->setShortcuts(QKeySequence::SaveAs);

    QAction *exitAct = fileMenu->addAction(tr("E&xit"), this, &QWidget::close);
    exitAct->setShortcuts(QKeySequence::Quit);

    menuBar()->addSeparator();

    QMenu *helpMenu = menuBar()->addMenu(tr("&Help"));
    helpMenu->addAction(tr("&About"), this, &MainWindow::about);
    helpMenu->addAction(tr("About &Qt"), qApp, &QApplication::aboutQt);
}

Esto crea el menú que se muestra en las capturas de pantalla siguientes:

Menú «Archivo» con las opciones «Abrir», «Guardar como» y «Salir»Menú de ayuda con «Acerca de» y «Acerca de Qt»

La función ` open() `, cuando se activa, muestra al usuario un cuadro de diálogo de archivos para seleccionar un archivo de marcadores. Si se selecciona un archivo, este se analiza mediante un ` XBelReader ` para rellenar el ` treeWidget ` con los marcadores. Si surgen problemas al abrir o analizar el archivo, se muestra al usuario un mensaje de advertencia adecuado, que incluye el nombre del archivo y el mensaje de error. De lo contrario, se muestran los marcadores leídos del archivo y la barra de estado de la ventana indica brevemente que el archivo se ha cargado.

void MainWindow::open()
{
    QFileDialog fileDialog(this, tr("Open Bookmark File"), QDir::currentPath());
    fileDialog.setMimeTypeFilters({"application/x-xbel"_L1});
    if (fileDialog.exec() != QDialog::Accepted)
        return;

    treeWidget->clear();

    const QString fileName = fileDialog.selectedFiles().constFirst();
    QFile file(fileName);
    if (!file.open(QFile::ReadOnly | QFile::Text)) {
        QMessageBox::warning(this, tr("QXmlStream Bookmarks"),
                             tr("Cannot read file %1:\n%2.")
                                     .arg(QDir::toNativeSeparators(fileName), file.errorString()));
        return;
    }

    XbelReader reader(treeWidget);
    if (!reader.read(&file)) {
        QMessageBox::warning(
                this, tr("QXmlStream Bookmarks"),
                tr("Parse error in file %1:\n\n%2")
                        .arg(QDir::toNativeSeparators(fileName), reader.errorString()));
    } else {
        statusBar()->showMessage(tr("File loaded"), 2000);
    }
}

La función ` saveAs() ` muestra un cuadro de diálogo ` QFileDialog` en el que se solicita al usuario una ruta ` fileName` en la que guardar una copia de los datos de los marcadores. Al igual que la función ` open() `, esta función también muestra un mensaje de advertencia si no es posible escribir en el archivo.

void MainWindow::saveAs()
{
    QFileDialog fileDialog(this, tr("Save Bookmark File"), QDir::currentPath());
    fileDialog.setAcceptMode(QFileDialog::AcceptSave);
    fileDialog.setDefaultSuffix("xbel"_L1);
    fileDialog.setMimeTypeFilters({"application/x-xbel"_L1});
    if (fileDialog.exec() != QDialog::Accepted)
        return;

    const QString fileName = fileDialog.selectedFiles().constFirst();
    QFile file(fileName);
    if (!file.open(QFile::WriteOnly | QFile::Text)) {
        QMessageBox::warning(this, tr("QXmlStream Bookmarks"),
                             tr("Cannot write file %1:\n%2.")
                                     .arg(QDir::toNativeSeparators(fileName), file.errorString()));
        return;
    }

    XbelWriter writer(treeWidget);
    if (writer.writeFile(&file))
        statusBar()->showMessage(tr("File saved"), 2000);
}

La función ` about() ` muestra un ` QMessageBox ` con una breve descripción del ejemplo, o información general sobre Qt y la versión que se está utilizando.

void MainWindow::about()
{
    QMessageBox::about(this, tr("About QXmlStream Bookmarks"),
                       tr("The <b>QXmlStream Bookmarks</b> example demonstrates how to use Qt's "
                          "QXmlStream classes to read and write XML documents."));
}

main() Función

La función ` main() ` crea una instancia de ` MainWindow ` e invoca la función ` show() ` para mostrarla; a continuación, invoca ` open()`, ya que es muy probable que esto sea lo primero que el usuario desee hacer.

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);
    MainWindow mainWin;
    mainWin.show();
    mainWin.open();
    return app.exec();
}

Consulta la página de recursos del lenguaje de intercambio de marcadores XML (XBEL) para obtener más información sobre los archivos XBEL.

Proyecto de ejemplo en code.qt.io

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