Structure des documents texte

From Apache OpenOffice Wiki
Jump to: navigation, search
doc OOo
Book.png

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.

Documentation note.png La procédure d'accès aux paragraphes d'un texte qui est décrite ici est comparable à la liste Paragraphs disponible dans les objets Range et Document de VBA. Cependant, contrairement à VBA où les paragraphes sont accessibles par leur indice (via l'appel Paragraph(1), par exemple), dans Apache OpenOffice Basic, il est nécessaire d'utiliser l'objet Enumeration décrit ci-dessus.

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.

Documentation note.png Dans VBA, les propriétés de formatage d'un objet se répartissent généralement sur toute une gamme de sous-objets (Range.Font, Range.Borders, Range.Shading, Range.ParagraphFormat, par exemple). On accède à ces propriétés par des expressions en cascade (Range.Font.AllCaps, par exemple). Dans Apache OpenOffice Basic, en revanche, les propriétés de formatage sont accessibles directement, à l'aide des objets concernés (TextCursor, Paragraph, etc.). Les propriétés de caractère et de paragraphe disponibles dans Apache OpenOffice sont présentées dans les deux sections suivantes.
Documentation note.png 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).


Retrieved from "https://wiki.openoffice.org/w/index.php?title=FR/Documentation/BASIC_Guide/Structure_of_Text_Documents&oldid=240396"
Personal tools