Structure des documents en texte enrichi

Les documents texte sont représentés par la classe ` QTextDocument `, qui contient des informations sur la représentation interne du document et sa structure, et qui conserve la trace des modifications afin de permettre les 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.

De nouveaux éléments sont créés et insérés dans le document par programmation à l’aide d’un QTextCursor ou à l’aide d’un widget d’édition, tel qu’ QTextEdit. Les éléments peuvent se voir attribuer un format particulier lors de leur création ; dans le cas contraire, ils reprennent le format actuel du curseur pour cet élément.

Structure de base Le « niveau supérieur » d’un document peut être structuré comme illustré. Chaque document contient toujours un cadre racine, qui contient lui-même au moins un bloc de texte. Pour les documents comportant du 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 analyser leur contenu. L'édition de documents est décrite dans la section « L'interface QTextCursor ».

Documents en texte enrichi

QTextDocument Les objets contiennent toutes les informations nécessaires à la construction de documents en texte enrichi. Les documents texte sont accessibles de deux manières complémentaires : sous la forme d’un tampon linéaire destiné aux éditeurs, et sous la forme d’une hiérarchie d’objets utile aux moteurs de mise en page. Dans le modèle hiérarchique du document, les objets correspondent généralement à des éléments visuels tels que les cadres, les tableaux et les listes. À un niveau plus bas, 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 de son contenu.

Bien que QTextEdit facilite l’affichage et l’édition de texte enrichi, 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 en texte enrichi sans la surcharge liée à l’utilisation de plusieurs widgets d’édition, ni sans nécessiter que les documents soient stockés dans un format intermédiaire.

Un document vide contient un cadre racine qui, lui-même, contient un seul bloc de texte vide. Les cadres assurent une séparation logique entre les différentes parties du document, mais possèdent également des propriétés qui déterminent leur apparence lors du rendu. Un tableau est un type de cadre spécialisé composé d’un certain nombre de cellules, organisées en lignes et en colonnes, dont chacune peut contenir une structure et du texte supplémentaires. Les tableaux offrent des fonctionnalités 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, dont chacun spécifie des informations relatives au format du texte et des caractères. Les propriétés textuelles sont définies à la fois au niveau du caractère et au niveau du bloc. Au niveau du caractère, des propriétés telles que la famille de polices, la couleur du texte et l’épaisseur de la police peuvent être spécifiées. Les propriétés au niveau du bloc contrôlent l’apparence et le comportement globaux du texte, tels que le sens de l’écoulement du texte, l’alignement et la couleur d’arrière-plan.

La structure du document n’est pas manipulée directement. L’édition s’effectue via une interface à curseur. L’interface du curseur de 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.

On obtient le cadre racine de la manière suivante :

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

Lors de la navigation dans la structure du document, il est utile de commencer par le cadre racine, car celui-ci donne accès à l'ensemble de la structure du document.

Éléments du document

Les documents en texte enrichi se composent généralement d’éléments courants tels que des paragraphes, des cadres, des tableaux et des listes. Ceux-ci sont représentés dans un 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 permet de les placer en ligne avec le texte environnant, en conservant leur mise en forme.

Les éléments structurels de base des documents sont les éléments « QTextBlock » et « QTextFrame ». Les blocs contiennent eux-mêmes des fragments de texte enrichi (QTextFragment), mais ceux-ci n’influencent pas directement la structure de haut niveau d’un document.

Les éléments pouvant regrouper d’autres éléments du 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`, tandis que 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 présentant différents formats de caractères et servent à représenter les paragraphes du document. Chaque bloc contient généralement plusieurs fragments de texte aux styles variés. Les fragments sont créés lors de l’insertion de texte dans le document, et d’autres s’y ajoutent au fur et à mesure que le document est modifié. Le document divise, fusionne et supprime des fragments afin de représenter efficacement les différents styles de texte au sein du bloc.

Les fragments d’un bloc donné peuvent être examinés à l’aide d’un ` QTextBlock::iterator ` permettant de 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 les éléments d’une liste. Par conséquent, les blocs peuvent définir leurs propres formats de caractères, qui contiennent des informations sur la mise en forme au niveau du bloc, telles que le type de puces utilisées pour les éléments de liste. La mise en forme du bloc lui-même est décrite par la classe « QTextBlockFormat » et définit 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, dès lors que nous disposons d’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!=()` servent à vérifier si deux blocs sont identiques, tandis que ` operator<()` permet de déterminer lequel apparaît en premier dans un document.

Cadres

Les cadres sont fournis par la classe QTextFrame.

Les cadres 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 affiché et positionné sur la page. Les cadres sont soit insérés dans le flux de texte, soit alignés à gauche ou à droite de la page. Chaque document contient un cadre racine qui renferme tous les autres éléments du document. Par conséquent, tous les cadres, à l’exception du cadre racine, ont un cadre parent.

Comme les blocs de texte servent à séparer d’autres éléments du document, chaque cadre contient toujours au moins un bloc de texte et zéro ou plusieurs cadres enfants. Nous pouvons inspecter le contenu d’un cadre en utilisant un itérateur de cadre ( QTextFrame::iterator ) pour parcourir ses éléments enfants :

    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 fait référence. Cela nous permet de parcourir la structure du document cadre par cadre tout en accédant 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 gérés par la classe ` QTextTable `.

Les tableaux sont des ensembles de cellules organisées en lignes et en colonnes. Chaque cellule de tableau est un élément du document doté de 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 créées automatiquement 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`, les tableaux sont donc traités comme des cadres dans la structure du document. Pour chaque cadre rencontré dans le document, nous pouvons vérifier s’il s’agit d’un tableau et le traiter différemment :

    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 offrent également les décorations standard des listes, telles que les puces et les numéros. Les listes peuvent être imbriquées et seront indentées si le format de la liste spécifie une indentation non nulle.

On peut faire référence à chaque élément de la liste par son index dans la liste :

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

Comme ` QTextList ` est une sous-classe de ` QTextBlockGroup`, elle ne regroupe pas les éléments de la liste en tant qu’éléments enfants, mais fournit à la place diverses fonctions pour les gérer. Cela signifie que tout bloc de texte rencontré lors de la traversée d’un document peut en réalité être un élément de liste. On peut s’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ères du fragment de texte correspondant à 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 représentant l’image peut être identifié en parcourant les fragments du bloc de texte qui contient l’image.