Structure d'un document texte riche

Les documents texte sont représentés par la classe QTextDocument, qui contient des informations sur la représentation interne du document, sa structure, et conserve la trace des modifications pour fournir des fonctions d'annulation et de rétablissement.

La représentation structurée d'un document texte présente son contenu sous la forme d'une hiérarchie de blocs de texte, de cadres, de tableaux et d'autres objets. Ceux-ci fournissent une structure logique au document et décrivent la manière dont leur contenu sera affiché. En général, les cadres et les tableaux sont utilisés pour regrouper d'autres structures, tandis que les blocs de texte contiennent les informations textuelles proprement dites.

Les nouveaux éléments sont créés et insérés dans le document par programmation à l'aide d'un QTextCursor ou d'un widget d'éditeur, tel que QTextEdit. Les éléments peuvent se voir attribuer un format particulier lors de leur création ; dans le cas contraire, ils prennent le format courant du curseur pour l'élément.

Structure de base Le "niveau supérieur" d'un document peut être peuplé de la manière indiquée. Chaque document contient toujours un cadre racine, qui contient toujours au moins un bloc de texte. Pour les documents ayant un contenu textuel, le cadre racine contient généralement une séquence de blocs et d'autres éléments. Dans un document, les séquences de cadres et de tableaux sont toujours séparées par des blocs de texte, même si ces derniers ne contiennent aucune information. Cela garantit que de nouveaux éléments peuvent toujours être insérés entre les structures existantes.

Dans ce chapitre, nous examinons chacun des éléments structurels utilisés dans un document de texte enrichi, nous décrivons leurs caractéristiques et leurs utilisations, et nous montrons comment examiner leur contenu. L'édition des documents est décrite dans l'interface QTextCursor.

Documents de texte enrichi

QTextDocument Les objets QTextCursor contiennent toutes les informations nécessaires à la construction de documents de texte riche. Les documents texte sont accessibles de deux manières complémentaires : sous la forme d'une mémoire tampon linéaire à l'usage des éditeurs et sous la forme d'une hiérarchie d'objets utile aux moteurs de mise en page. Dans le modèle de document hiérarchique, les objets correspondent généralement à des éléments visuels tels que des cadres, des tableaux et des listes. À un niveau inférieur, ces éléments décrivent des propriétés telles que le style et l'alignement du texte. La représentation linéaire du document est utilisée pour l'édition et la manipulation du contenu du document.

Bien que QTextEdit facilite l'affichage et l'édition de texte riche, les documents peuvent également être utilisés indépendamment de tout widget d'éditeur, par exemple :

QTextDocument *newDocument = new QTextDocument;

Ils peuvent également être extraits d'un éditeur existant :

QTextEdit *editor = new QTextEdit;
QTextDocument *editorDocument = editor->document();

Cette flexibilité permet aux applications de gérer plusieurs documents de texte enrichi sans avoir à gérer plusieurs widgets d'édition ou à stocker les documents dans un format intermédiaire.

Un document vide contient un cadre racine qui contient lui-même un seul bloc de texte vide. Les cadres fournissent une séparation logique entre les parties du document, mais ont également des propriétés qui déterminent la façon dont ils apparaîtront lors du rendu. Un tableau est un type de cadre spécialisé qui se compose d'un certain nombre de cellules, disposées en lignes et en colonnes, chacune d'entre elles pouvant contenir une structure et un texte supplémentaires. Les tableaux offrent des fonctions de gestion et de mise en page qui permettent de créer des configurations flexibles de cellules.

Les blocs de texte contiennent des fragments de texte, chacun d'entre eux spécifiant des informations sur le texte et le format des caractères. Les propriétés textuelles sont définies à la fois au niveau des caractères et au niveau des blocs. Au niveau des caractères, des propriétés telles que la famille de polices, la couleur du texte et la graisse de la police peuvent être spécifiées. Les propriétés au niveau du bloc contrôlent l'apparence et le comportement du texte à un niveau supérieur, comme la direction du flux de texte, l'alignement et la couleur d'arrière-plan.

La structure du document n'est pas manipulée directement. L'édition s'effectue par le biais d'une interface basée sur un curseur. L'interface du curseur texte insère automatiquement de nouveaux éléments de document dans le cadre racine et veille à ce qu'il soit complété par des blocs vides si nécessaire.

Nous obtenons le cadre racine de la manière suivante :

    QTextDocument *editorDocument = editor->document();
    QTextFrame *root = editorDocument->rootFrame();

Lorsque l'on navigue dans la structure du document, il est utile de commencer par le cadre racine car il permet d'accéder à l'ensemble de la structure du document.

Éléments du document

Les documents en texte enrichi se composent généralement d'éléments communs tels que des paragraphes, des cadres, des tableaux et des listes. Ces éléments sont représentés dans un site QTextDocument par les classes QTextBlock, QTextFrame, QTextTable et QTextList. Contrairement aux autres éléments d'un document, les images sont représentées par des fragments de texte spécialement formatés. Cela leur permet d'être placées en ligne avec le texte environnant.

Les blocs structurels de base des documents sont QTextBlock et QTextFrame. Les blocs contiennent eux-mêmes des fragments de texte riche (QTextFragment), mais ceux-ci n'influencent pas directement la structure de haut niveau d'un document.

Les éléments qui peuvent regrouper d'autres éléments de document sont généralement des sous-classes de QTextObject et se répartissent en deux catégories : Les éléments qui regroupent des blocs de texte sont des sous-classes de QTextBlockGroup, et ceux qui regroupent des cadres et d'autres éléments sont des sous-classes de QTextFrame.

Blocs de texte

Les blocs de texte sont fournis par la classe QTextBlock.

Les blocs de texte regroupent des fragments de texte avec différents formats de caractères et sont utilisés pour représenter des paragraphes dans le document. Chaque bloc contient généralement un certain nombre de fragments de texte de styles différents. Les fragments sont créés lorsque le texte est inséré dans le document, et d'autres sont ajoutés lorsque le document est édité. Le document divise, fusionne et supprime les fragments pour représenter efficacement les différents styles de texte dans le bloc.

Les fragments d'un bloc donné peuvent être examinés à l'aide d'un site QTextBlock::iterator pour parcourir la structure interne du bloc :

    QTextBlock::iterator it;
    for (it = currentBlock.begin(); !(it.atEnd()); ++it) {
        QTextFragment currentFragment = it.fragment();
        if (currentFragment.isValid())
            processFragment(currentFragment);
    }

Les blocs sont également utilisés pour représenter des éléments de liste. Par conséquent, les blocs peuvent définir leurs propres formats de caractères qui contiennent des informations sur la décoration au niveau du bloc, comme le type de puces utilisé pour les éléments de liste. Le formatage du bloc lui-même est décrit par la classe QTextBlockFormat et décrit des propriétés telles que l'alignement du texte, l'indentation et la couleur d'arrière-plan.

Bien qu'un document donné puisse contenir des structures complexes, une fois que nous avons une référence à un bloc valide dans le document, nous pouvons naviguer entre chacun des blocs de texte dans l'ordre dans lequel ils ont été écrits :

    QTextBlock currentBlock = textDocument->begin();

    while (currentBlock.isValid()) {
        processBlock(currentBlock);
        currentBlock = currentBlock.next();
    }

Cette méthode est utile lorsque vous souhaitez extraire uniquement le texte enrichi d'un document, car elle ignore les cadres, les tableaux et les autres types de structure.

QTextBlock fournit des opérateurs de comparaison qui facilitent la manipulation des blocs : operator==() et operator!=() sont utilisés pour tester si deux blocs sont identiques, et operator<() est utilisé pour déterminer lequel apparaît en premier dans un document.

Cadres

Les cadres sont fournis par la classe QTextFrame.

Les blocs de texte regroupent des blocs de texte et des cadres enfants, créant ainsi des structures de document plus grandes que des paragraphes. Le format d'un cadre spécifie la manière dont il est rendu et positionné sur la page. Les cadres sont insérés dans le flux de texte ou flottent à gauche ou à droite de la page. Chaque document contient un cadre racine qui contient tous les autres éléments du document. Par conséquent, tous les cadres, à l'exception du cadre racine, ont un cadre parent.

Étant donné que les blocs de texte sont utilisés pour séparer les autres éléments du document, chaque bloc contiendra toujours au moins un bloc de texte et zéro ou plusieurs cadres enfants. Nous pouvons inspecter le contenu d'un bloc en utilisant un QTextFrame::iterator pour parcourir les éléments enfants du bloc :

    QTextFrame::iterator it;
    for (it = frame->begin(); !(it.atEnd()); ++it) {

        QTextFrame *childFrame = it.currentFrame();
        QTextBlock childBlock = it.currentBlock();

        if (childFrame)
            processFrame(childFrame);
        else if (childBlock.isValid())
            processBlock(childBlock);
    }

Notez que l'itérateur sélectionne à la fois les cadres et les blocs, il est donc nécessaire de vérifier à quoi il se réfère. Cela nous permet de naviguer dans la structure du document cadre par cadre tout en continuant à accéder aux blocs de texte si nécessaire. Les classes QTextBlock::iterator et QTextFrame::iterator peuvent être utilisées de manière complémentaire pour extraire la structure requise d'un document.

Tableaux

Les tableaux sont fournis par la classe QTextTable.

Les tableaux sont des collections de cellules disposées en lignes et en colonnes. Chaque cellule de tableau est un élément de document avec son propre format de caractères, mais elle peut également contenir d'autres éléments, tels que des cadres et des blocs de texte. Les cellules de tableau sont automatiquement créées lors de la construction du tableau, ou lorsque des lignes ou des colonnes supplémentaires sont ajoutées. Elles peuvent également être déplacées d'un tableau à l'autre.

QTextTable est une sous-classe de QTextFrame, de sorte que les tableaux sont traités comme des cadres dans la structure du document. Pour chaque cadre que nous rencontrons dans le document, nous pouvons vérifier s'il représente un tableau et le traiter d'une manière différente :

    QTextFrame::iterator it;
    for (it = frame->begin(); !(it.atEnd()); ++it) {

        QTextFrame *childFrame = it.currentFrame();
        QTextBlock childBlock = it.currentBlock();

        if (childFrame) {
            QTextTable *childTable = qobject_cast<QTextTable*>(childFrame);

            if (childTable)
                processTable(childTable);
            else
                processFrame(childFrame);

        } else if (childBlock.isValid()) {
            processBlock(childBlock);
        }
    }

Les cellules d'un tableau existant peuvent être examinées en parcourant les lignes et les colonnes.

    for (int row = 0; row < table->rows(); ++row) {
        for (int column = 0; column < table->columns(); ++column) {
            QTextTableCell tableCell = table->cellAt(row, column);
            processTableCell(tableCell);
        }
    }

Listes

Les listes sont fournies par la classe QTextList.

Les listes sont des séquences de blocs de texte formatés de la manière habituelle, mais qui fournissent également les décorations de liste standard telles que les puces et les éléments énumérés. Les listes peuvent être imbriquées et seront indentées si le format de la liste spécifie une indentation non nulle.

Chaque élément d'une liste peut être désigné par son indice dans la liste :

    for (int index = 0; index < list->count(); ++index) {
        QTextBlock listItem = list->item(index);
        processListItem(listItem);
    }

Étant donné que QTextList est une sous-classe de QTextBlockGroup, il ne regroupe pas les éléments de la liste en tant qu'éléments enfants, mais fournit diverses fonctions pour les gérer. Cela signifie que tout bloc de texte que nous trouvons en parcourant un document peut en fait être un élément de liste. Nous pouvons nous assurer que les éléments de liste sont correctement identifiés en utilisant le code suivant :

    QTextFrame::iterator it;
    for (it = frame->begin(); !(it.atEnd()); ++it) {

        QTextBlock block = it.currentBlock();

        if (block.isValid()) {

            QTextList *list = block.textList();

            if (list) {
                int index = list->itemNumber(block);
                processListItem(list, index);
            }
        }
    }

Images

Dans QTextDocument, les images sont représentées par des fragments de texte qui font référence à des images externes via le mécanisme des ressources. Les images sont créées à l'aide de l'interface du curseur et peuvent être modifiées ultérieurement en changeant le format de caractère du fragment de texte de l'image :

    if (fragment.isValid()) {
        QTextImageFormat newImageFormat = fragment.charFormat().toImageFormat();

        if (newImageFormat.isValid()) {
            newImageFormat.setName(":/images/newimage.png");
            QTextCursor helper = cursor;

            helper.setPosition(fragment.position());
            helper.setPosition(fragment.position() + fragment.length(),
                                QTextCursor::KeepAnchor);
            helper.setCharFormat(newImageFormat);
        }
    }

Le fragment qui représente l'image peut être trouvé en itérant sur les fragments dans le bloc de texte qui contient l'image.