Structure des documents texte
- Structure des documents texte
- Édition des documents texte
- Documents texte : plus que du texte
Un document texte peut contenir quatre types d'informations :
- le texte proprement dit ;
- des modèles de formatage des caractères, des paragraphes et des pages ;
- des éléments non textuels tels que des tableaux, des images et des objets de dessin ;
- des paramètres globaux pour le document texte.
Cette section est dédiée au texte et aux options de formatage associées.
Paragraphes et portions de paragraphe
La partie essentielle d'un document texte est constituée d'une suite de paragraphes. Ceux-ci n'étant ni nommés ni indexés, il est impossible d'accéder directement à l'un d'eux. Vous pouvez néanmoins les parcourir de manière séquentielle à l'aide de l'objet Enumeration décrit au chapitre Introduction à l'API. Cela permet d'éditer les paragraphes.
Lorsque vous utilisez l'objet Enumeration, il faut néanmoins prendre en compte une particularité : il ne retourne pas uniquement les paragraphes, mais également les tableaux (à strictement parler, dans Apache OpenOffice Writer, un tableau est un type spécial de paragraphe). C'est pourquoi, avant d'accéder à un objet retourné, vous devez vérifier qu'il prend en charge le service com.sun.star.text.Paragraph (s'il s'agit d'un paragraphe) ou le service com.sun.star.text.TextTable (s'il s'agit d'un tableau).
L'exemple suivant parcourt le contenu d'un document texte dans une boucle et utilise un message dans chaque cas pour indiquer à l'utilisateur si l'objet en question est un paragraphe ou un tableau.
Dim Doc As Object Dim Enum As Object Dim TextElement As Object ' Create document object Doc = StarDesktop.CurrentComponent ' Create enumeration object Enum = Doc.Text.createEnumeration ' loop over all text elements While Enum.hasMoreElements TextElement = Enum.nextElement If TextElement.supportsService("com.sun.star.text.TextTable") Then MsgBox "The current block contains a table." End If If TextElement.supportsService("com.sun.star.text.Paragraph") Then MsgBox "The current block contains a paragraph." End If Wend
Cet exemple crée un objet Document Doc qui référence le document Apache OpenOffice actif. L'objet Doc est ensuite utilisé pour créer un objet Enumeration qui parcourt chaque partie du texte (paragraphes et tableaux) et assigne l'élément actif à l'objet TextElement. La méthode supportsService détermine si TextElement est un paragraphe ou un tableau.
Paragraphes
Le service com.sun.star.text.Paragraph permet d'accéder au contenu d'un paragraphe. Le texte du paragraphe peut être extrait et modifié à l'aide de la propriété String :
Dim Doc As Object Dim Enum As Object Dim TextElement As Object Doc = StarDesktop.CurrentComponent Enum = Doc.Text.createEnumeration While Enum.hasMoreElements TextElement = Enum.nextElement If TextElement.supportsService("com.sun.star.text.Paragraph") Then TextElement.String = Replace(TextElement.String, "you", "U") TextElement.String = Replace(TextElement.String, "too", "2") TextElement.String = Replace(TextElement.String, "for", "4") End If Wend
Cet exemple ouvre le document texte actif et le parcourt à l'aide de l'objet Enumeration. Il utilise la propriété TextElement.String dans tous les paragraphes pour accéder aux paragraphes concernés et remplace les chaînes you, too and for par les caractères U, 2 and 4. La fonction Replace utilisée pour la substitution n'entre pas dans le domaine linguistique standard de Apache OpenOffice Basic. Il s'agit d'une nouvelle utilisation de la fonction d'exemple décrite à la section Recherche et remplacement.
Apache OpenOffice Basic ne présente aucun équivalent des listes Characters, Sentences et Words fournies dans VBA. En revanche, vous pouvez utiliser un objet TextCursor permettant la navigation à l'échelle des caractères, des phrases et des mots.
Portions de paragraphe
L'exemple précédent peut effectuer les substitutions souhaitées dans le texte, mais il peut également détruire le formatage.
En effet, un paragraphe est constitué de sous-objets individuels. Chacun de ces sous-objets contient ses propres informations de formatage. Par exemple, si un paragraphe contient en son milieu un mot en gras, il est représenté dans Apache OpenOffice par trois portions de paragraphe : la portion précédant le mot en gras, le mot en gras lui-même et la portion située après, définie de nouveau comme normale.
Si le texte du paragraphe est modifié à l'aide de la propriété String du paragraphe, Apache OpenOffice commence par supprimer les anciennes portions du paragraphe et en insère une nouvelle. Le formatage des sections précédentes est alors perdu.
Pour éviter cela, l'utilisateur peut accéder aux portions concernées du paragraphe au lieu du paragraphe entier. C'est pourquoi les paragraphes comportent leur propre objet Enumeration. Dans l'exemple suivant, une double boucle parcourt tous les paragraphes d'un document texte et les portions de paragraphes qu'ils contiennent, puis applique les remplacements de l'exemple précédent :
Dim Doc As Object Dim Enum1 As Object Dim Enum2 As Object Dim TextElement As Object Dim TextPortion As Object Doc = StarDesktop.CurrentComponent Enum1 = Doc.Text.createEnumeration ' loop over all paragraphs While Enum1.hasMoreElements TextElement = Enum1.nextElement If TextElement.supportsService("com.sun.star.text.Paragraph") Then Enum2 = TextElement.createEnumeration ' loop over all sub-paragraphs While Enum2.hasMoreElements TextPortion = Enum2.nextElement MsgBox "'" & TextPortion.String & "'" TextPortion.String = Replace(TextPortion.String, "you", "U") TextPortion.String = Replace(TextPortion.String, "too", "2") TextPortion.String = Replace(TextPortion.String, "for", "4") Wend End If Wend
L'exemple parcourt un document texte par une double boucle. La boucle externe se rapporte aux paragraphes du texte. La boucle interne traite les portions de paragraphe à l'intérieur de ces paragraphes. Le contenu de chacune de ces portions de paragraphe est modifié à l'aide de la propriété String de la chaîne, comme l'exemple précédent le faisait pour les paragraphes. Toutefois, les portions de paragraphe étant modifiées directement, leur formatage est conservé lors du remplacement de la chaîne.
Formatage
Le texte peut être formaté de différentes façons. La manière la plus simple consiste à assigner les propriétés de format directement à la séquence de texte. On parle dans ce cas de formatage direct. Le formatage direct est particulièrement utilisé dans les documents courts, car les formats peuvent être assignés par l'utilisateur à l'aide de la souris. Vous pouvez, par exemple, mettre en valeur un mot à l'intérieur du texte en le mettant en gras ou centrer une ligne.
Outre le formatage direct, il est également possible de formater le texte à l'aide de modèles. On parle alors de formatage indirect. Avec le formatage indirect, l'utilisateur assigne un modèle prédéfini à la portion de texte concernée. Si la présentation du texte est modifiée par la suite, il suffit à l'utilisateur de modifier le modèle. Apache OpenOffice modifie alors la manière dont toutes les portions de texte utilisant ce modèle sont représentées.
Les propriétés de formatage figurent dans chaque objet (Paragraph, TextCursor, etc.) et peuvent être appliquées directement. |
Propriétés de caractère
Les propriétés de format relatives à un caractère sont décrites comme propriétés de caractère. Elles comprennent notamment le type de gras et le type de police. Les objets permettant de définir des propriétés de caractère doivent prendre en charge le service com.sun.star.style.CharacterProperties. Apache OpenOffice reconnaît une gamme étendue de services prenant en charge ce service. C'est le cas des services com.sun.star.text.Paragraph (pour les paragraphes) et com.sun.star.text.TextPortion (pour les portions de paragraphes) décrits précédemment.
Le service com.sun.star.style.CharacterProperties ne fournit aucune interface, mais une gamme de propriétés permettant de définir et d'appeler des propriétés de caractère. La liste complète des propriétés de caractère est disponible dans la référence de l'API Apache OpenOffice. Les plus importantes sont répertoriées ci-dessous :
- CharFontName (String)
- nom du type de police sélectionné.
- CharColor (Long)
- couleur du texte.
- CharHeight (Float)
- hauteur des caractères en points (pt).
- CharUnderline (Constant group)
- type de soulignage (constantes correspondant à com.sun.star.awt.FontUnderline).
- CharWeight (Constant group)
- graisse de police (constantes correspondant à com.sun.star.awt.FontWeight).
- CharBackColor (Long)
- couleur d'arrière-plan.
- CharKeepTogether (Boolean)
- suppression des retours à la ligne automatiques.
- CharStyleName (String)
- nom du modèle de caractère.
Propriétés de paragraphe
Les informations de formatage qui ne se rapportent pas à des caractères individuels, mais à un paragraphe entier, sont considérées comme des propriétés de paragraphe. Cela inclut les interlignes et la distance entre le paragraphe et le bord de la page. Les propriétés de paragraphe sont accessibles via le service com.sun.star.style.ParagraphProperties.
Même les propriétés de paragraphe sont disponibles dans divers objets. Tous les objets prenant en charge le service com.sun.star.text.Paragraph prennent également en charge les propriétés de paragraphe dans com.sun.star.style.ParagraphProperties.
La liste complète des propriétés de paragraphe est disponible dans la référence de l'API Apache OpenOffice. Les plus courantes sont les suivantes :
- ParaAdjust (enum)
- orientation verticale du texte (constantes correspondant à com.sun.star.style.ParagraphAdjust).
- ParaLineSpacing (struct)
- interligne (structure correspondant à com.sun.star.style.LineSpacing).
- ParaBackColor (Long)
- couleur d'arrière-plan.
- ParaLeftMargin (Long)
- marge gauche en centièmes de millimètre.
- ParaRightMargin (Long)
- marge droite en centièmes de millimètre.
- ParaTopMargin (Long)
- marge supérieure en centièmes de millimètre.
- ParaBottomMargin (Long)
- marge inférieure en centièmes de millimètre.
- ParaTabStops (Array of struct)
- type et position des tabulations (tableau de structures du type com.sun.star.style.TabStop).
- ParaStyleName (String)
- nom du modèle de paragraphe.
Exemple : export HTML simple
L'exemple suivant illustre la manipulation des informations de formatage. Il procède par itérations à l'intérieur d'un document texte et crée un fichier HTML simple. Dans ce but, chaque paragraphe est enregistré dans son propre élément HTML <P>. Les portions de paragraphe affichées en gras sont marquées à l'aide d'un élément HTML <B> lors de leur export.
Dim FileNo As Integer, Filename As String, CurLine As String Dim Doc As Object Dim Enum1 As Object, Enum2 As Object Dim TextElement As Object, TextPortion As Object Filename = "c:\text.html" FileNo = Freefile Open Filename For Output As #FileNo Print #FileNo, "<HTML><BODY>" Doc = StarDesktop.CurrentComponent Enum1 = Doc.Text.createEnumeration ' loop over all paragraphs While Enum1.hasMoreElements TextElement = Enum1.nextElement If TextElement.supportsService("com.sun.star.text.Paragraph") Then Enum2 = TextElement.createEnumeration CurLine = "<P>" ' loop over all paragraph portions While Enum2.hasMoreElements TextPortion = Enum2.nextElement If TextPortion.CharWeight = com.sun.star.awt.FontWeight.BOLD THEN CurLine = CurLine & "<B>" & TextPortion.String & "</B>" Else CurLine = CurLine & TextPortion.String End If Wend ' output the line CurLine = CurLine & "</P>" Print #FileNo, CurLine End If Wend ' write HTML footer Print #FileNo, "</BODY></HTML>" Close #FileNo
La structure de base de cet exemple reprend celle des exemples parcourant les portions de paragraphe d'un texte, présentés plus haut. Les fonctions d'écriture du fichier HTML, ainsi qu'un bloc de test vérifiant la graisse des portions de texte correspondantes et mettant en gras des portions de paragraphe à l'aide d'une balise HTML correspondante, ont été ajoutées.
Valeurs par défaut des propriétés de caractère et de paragraphe
Le formatage direct est toujours prioritaire sur le formatage indirect. Autrement dit, une priorité inférieure est attribuée au formatage à l'aide de modèles par rapport au formatage direct dans un texte.
Il n'est pas facile d'établir si une section d'un document a été formatée directement ou indirectement. Les barres de symboles fournies par Apache OpenOffice affichent les propriétés de texte courantes telles que le type de police, la graisse et la taille. Toutefois, elles n'indiquent pas si ces propriétés ont été définies par un modèle ou directement dans le texte.
Dans Apache OpenOffice Basic, la méthode getPropertyState permet aux programmeurs de vérifier le formatage d'une propriété. Elle prend le nom de la propriété en paramètre et retourne une constante indiquant l'origine du formatage. Les réponses suivantes, définies dans l'énumération com.sun.star.beans.PropertyState , sont possibles :
- com.sun.star.beans.PropertyState.DIRECT_VALUE
- la propriété est définie directement dans le texte (formatage direct).
- com.sun.star.beans.PropertyState.DEFAULT_VALUE
- la propriété est définie par un modèle (formatage indirect).
- com.sun.star.beans.PropertyState.AMBIGUOUS_VALUE
- la propriété est ambiguë. Cet état apparaît, par exemple, lorsque la méthode interroge la propriété graisse d'un paragraphe dont certains mots sont en gras et d'autres non.
L'exemple suivant illustre l'édition des propriétés de format dans Apache OpenOffice. Il recherche dans un texte les portions de paragraphe qui ont été définies en gras par formatage direct. S'il en trouve une, il supprime le formatage direct à l'aide de la méthode setPropertyToDefault et assigne un modèle de caractère MyBold à la portion de paragraphe.
Dim Doc As Object Dim Enum1 As Object Dim Enum2 As Object Dim TextElement As Object Dim TextPortion As Object Doc = StarDesktop.CurrentComponent Enum1 = Doc.Text.createEnumeration ' loop over all paragraphs While Enum1.hasMoreElements TextElement = Enum1.nextElement If TextElement.supportsService("com.sun.star.text.Paragraph") Then Enum2 = TextElement.createEnumeration ' loop over all paragraph portions While Enum2.hasMoreElements TextPortion = Enum2.nextElement If TextPortion.CharWeight = _ com.sun.star.awt.FontWeight.BOLD AND _ TextPortion.getPropertyState("CharWeight") = _ com.sun.star.beans.PropertyState.DIRECT_VALUE Then TextPortion.setPropertyToDefault("CharWeight") TextPortion.CharStyleName = "MyBold" End If Wend End If Wend
Content on this page is licensed under the Public Documentation License (PDL). |