Documents texte : plus que du texte
- Structure des documents texte
- Édition des documents texte
- Documents texte : plus que du texte
Jusqu'à présent, ce chapitre a uniquement abordé les paragraphes de texte et leurs portions. Toutefois les documents texte peuvent également contenir d'autres objets, notamment des tableaux, des dessins, des champs de texte et des répertoires. Tous ces objets peuvent être ancrés à un point quelconque du texte.
Grâce à ces fonctions communes, tous ces objets de Apache OpenOffice prennent en charge un service de base commun appelé com.sun.star.text.TextContent. Ce dernier fournit les propriétés suivantes :
- AnchorType (Enum)
- détermine le type d'ancre de l'objet TextContent, avec des valeurs par défaut correspondant à com.sun.star.text.TextContentAnchorType.
- AnchorTypes (sequence of Enum)
- énumération de tous les AnchorTypes qui prennent en charge un objet TextContent spécial.
- TextWrap (Enum)
- détermine le type d'habillage d'un objet TextContent, avec des valeurs par défaut correspondant à com.sun.star.text.WrapTextMode.
Les objets TextContent partagent également certaines méthodes, notamment celles qui permettent de créer, d'insérer et de supprimer des objets.
- Un nouvel objet TextContent est créé à l'aide de la méthode createInstance de l'objet Document.
- Un objet est inséré à l'aide de la méthode insertTextContent de l'objet Text.
- Les objets
TextContent sont supprimés à l'aide de la méthode removeTextContent.
Ces méthodes sont utilisées dans les exemples des sections suivantes.
Tableaux
L'exemple suivant crée un tableau à l'aide de la méthode createInstance décrite plus haut.
Dim Doc As Object Dim Table As Object Dim Cursor As Object Doc = StarDesktop.CurrentComponent Cursor = Doc.Text.createTextCursor() Table = Doc.createInstance("com.sun.star.text.TextTable") Table.initialize(5, 4) Doc.Text.insertTextContent(Cursor, Table, False)
Exemples Python :
def inset_img(): # abstract the objects in varialbes, doc, text and img, note we used the XSCRIPTCONTEXT doc = XSCRIPTCONTEXT.getDocument() text = doc.getText() cursor = text.createTextCursor() # not sure Table = doc.createInstance(u'com.sun.star.text.TextTable') # Verify code Table.initialize(5, 4) #inser the image in the text area location text.insertTextContent(text.getEnd(), Table, False)
Une fois le tableau créé, le nombre de lignes et le nombre de colonnes sont définis à l'aide d'un appel initialize, puis le tableau est inséré dans le document texte à l'aide de insertTextContent.
Comme le montre cet exemple, la méthode insertTextContent attend non seulement l'objet Content à insérer, mais également deux autres paramètres :
- un objet Cursor qui détermine la position d'insertion ;
- une variable booléenne indiquant si l'objet Content doit remplacer la sélection active du curseur (valeur True) ou être inséré dans le texte devant la sélection active (False)
Il est possible de déterminer les tableaux insérés dans un document texte à l'aide d'une simple boucle. On utilise pour cela la méthode getTextTables() de l'objet de document texte :
Dim Doc As Object Dim TextTables As Object Dim Table As Object Dim I As Integer Doc = StarDesktop.CurrentComponent TextTables = Doc.getTextTables() For I = 0 to TextTables.count - 1 Table = TextTables(I) ' Editing table Next I
Édition des tableaux
Un tableau est constitué de cellules individuelles. Ces cellules peuvent à leur tour contenir diverses autres cellules. À strictement parler, les colonnes de tableau n'existent pas dans Apache OpenOffice. Elles sont produites implicitement par la juxtaposition des cellules les unes en dessous des autres. Pour simplifier l'accès aux tableaux, Apache OpenOffice fournit néanmoins certaines méthodes fonctionnant avec des colonnes. Elles peuvent être utiles si aucune cellule du tableau n'a été fusionnée.
Commençons par examiner les propriétés du tableau lui-même. Elles sont définies dans le service com.sun.star.text.TextTable. Les propriétés les plus importantes de l'objet Table sont les suivantes :
- BackColor (Long)
- couleur d'arrière-plan du tableau.
- BottomMargin (Long)
- marge inférieure en centièmes de millimètre.
- LeftMargin (Long)
- marge gauche en centièmes de millimètre.
- RightMargin (Long)
- marge droite en centièmes de millimètre.
- TopMargin (Long)
- marge supérieure en centièmes de millimètre.
- RepeatHeadline (Boolean)
- répétition ou non de l'en-tête du tableau.
- Width (Long)
- largeur absolue du tableau en centièmes de millimètre.
Lignes
Un tableau est constitué d'une liste de lignes. L'exemple suivant illustre l'accès aux lignes d'un tableau et leur formatage.
Dim Doc As Object Dim Table As Object Dim Cursor As Object Dim Rows As Object Dim Row As Object Dim I As Integer Doc = StarDesktop.CurrentComponent Cursor = Doc.Text.createTextCursor() Table = Doc.createInstance("com.sun.star.text.TextTable") Table.initialize(5, 4) Doc.Text.insertTextContent(Cursor, Table, False) Rows = Table.getRows For I = 0 To Rows.getCount() - 1 Row = Rows.getByIndex(I) Row.BackColor = &HFF00FF Next
Cet exemple crée d'abord une liste contenant toutes les lignes à l'aide d'un appel Table.getRows. Les méthodes getCount et getByIndex permettent de poursuivre le traitement de la liste et appartiennent à l'interface com.sun.star.table.XtableRows. La méthode getByIndex retourne un objet Row qui prend en charge le service com.sun.star.text.TextTableRow.
Les méthodes centrales de l'interface com.sun.star.table.XtableRows sont les suivantes :
- getByIndex(Integer)
- retourne un objet Row pour l'indice spécifié.
- getCount()
- retourne le nombre d'objets Row.
- insertByIndex(Index, Count)
- insère Count lignes dans le tableau à partir de la position Index.
- removeByIndex(Index, Count)
- supprime Count lignes du tableau à partir de la position Index.
Les méthodes getByIndex et getCount sont disponibles dans tous les tableaux, tandis que les méthodes insertByIndex et removeByIndex ne peuvent être utilisées que dans les tableaux ne contenant pas de cellules fusionnées.
Le service com.sun.star.text.TextTableRow fournit les propriétés suivantes :
- BackColor (Long)
- couleur d'arrière-plan de la ligne.
- Height (Long)
- hauteur de la ligne en centièmes de millimètre.
- IsAutoHeight (Boolean)
- la hauteur du tableau s'adapte automatiquement au contenu.
- VertOrient (const)
- orientation verticale du cadre texte ; détails sur l'orientation verticale du texte à l'intérieur du tableau, avec des valeurs correspondant à com.sun.star.text.VertOrientation.
Colonnes
Les colonnes sont accessibles de la même manière que les lignes, à l'aide des méthodes getByIndex, getCount, insertByIndex et removeByIndex sur l'objet Column, qui est atteint via getColumns. Toutefois, vous ne pouvez utiliser ces méthodes que dans des tableaux ne contenant pas de cellules fusionnées. Les cellules ne peuvent pas être formatées par colonne dans Apache OpenOffice Basic. Pour arriver à ce résultat, il faut appliquer les méthodes de formatage des cellules individuelles.
Cellules
Chaque cellule d'un document Apache OpenOffice porte un nom unique. Si le curseur de Apache OpenOffice se trouve dans une cellule, le nom de cette cellule apparaît dans la barre d'état. La cellule supérieure gauche est habituellement appelée A1 et la cellule inférieure droite Xn, où X représente la lettre de la dernière colonne et n le numéro de la dernière ligne. Les objets Cell sont accessibles par la méthode getCellByName() de l'objet Table. Dans l'exemple suivant, une boucle parcourt toutes les cellules d'un tableau et y insère les numéros de ligne et lettres de colonne correspondants.
Dim Doc As Object Dim Table As Object Dim Cursor As Object Dim Rows As Object Dim RowIndex As Integer Dim Cols As Object Dim ColIndex As Integer Dim CellName As String Dim Cell As Object Doc = StarDesktop.CurrentComponent Cursor = Doc.Text.createTextCursor() Table = Doc.createInstance("com.sun.star.text.TextTable") Table.initialize(5, 4) Doc.Text.insertTextContent(Cursor, Table, False) Rows = Table.getRows Cols = Table.getColumns For RowIndex = 1 To Rows.getCount() For ColIndex = 1 To Cols.getCount() CellName = Chr(64 + ColIndex) & RowIndex Cell = Table.getCellByName(CellName) Cell.String = "row: " & CStr(RowIndex) + ", column: " & CStr(ColIndex) Next Next
Une cellule de tableau est comparable à du texte standard. Elle prend en charge l'interface createTextCursor permettant la création d'un objet TextCursor associé.
CellCursor = Cell.createTextCursor()
Toutes les options de formatage pour les caractères individuels et les paragraphes sont donc automatiquement disponibles.
L'exemple suivant effectue une recherche dans tous les tableaux d'un document texte et aligne à droite toutes les cellules comportant des valeurs numériques à l'aide de la propriété de paragraphe correspondante.
Dim Doc As Object Dim TextTables As Object Dim Table As Object Dim CellNames Dim Cell As Object Dim CellCursor As Object Dim I As Integer Dim J As Integer Doc = StarDesktop.CurrentComponent TextTables = Doc.getTextTables() For I = 0 to TextTables.count - 1 Table = TextTables(I) CellNames = Table.getCellNames() For J = 0 to UBound(CellNames) Cell = Table.getCellByName(CellNames(J)) If IsNumeric(Cell.String) Then CellCursor = Cell.createTextCursor() CellCursor.paraAdjust = com.sun.star.style.ParagraphAdjust.RIGHT End If Next Next
Cet exemple crée une liste TextTables contenant tous les tableaux d'un texte qui sont parcourus dans une boucle. Apache OpenOffice crée ensuite une liste des noms des cellules associés pour chacun de ces tableaux. Ces cellules sont ensuite parcourues à leur tour dans une boucle. Si une cellule contient une valeur numérique, l'exemple modifie le formatage en conséquence. Pour ce faire, il commence par créer un objet TextCursor renvoyant au contenu de la cellule, puis modifie les propriétés de paragraphe de cette dernière.
Cadres texte
Les cadres texte sont considérés comme des objets TextContent, tout comme les tableaux et les images. Ils consistent généralement en texte standard, mais ils peuvent être placés à tout emplacement sur la page et ne sont pas inclus dans l'enchaînement.
Comme pour tous les objets TextContent, la création d'un cadre texte et son insertion dans le document se font à deux étapes différentes.
Dim Doc As Object Dim TextTables As Object Dim Cursor As Object Dim Frame As Object Doc = StarDesktop.CurrentComponent Cursor = Doc.Text.createTextCursor() Frame = Doc.createInstance("com.sun.star.text.TextFrame") Doc.Text.insertTextContent(Cursor, Frame, False)
Le cadre texte est créé à l'aide de la méthode createInstance de l'objet Document. Le cadre texte créé de cette manière peut ensuite être inséré dans le document à l'aide de la méthode insertTextContent de l'objet Text. Pour cela, le nom du service com.sun.star.text.TextFrame approprié doit être spécifié.
L'emplacement d'insertion du cadre texte est déterminé par un objet Cursor, également exécuté lors de son insertion.
Les objets TextFrame fournissent toute une gamme de propriétés permettant d'agir sur l'emplacement et le comportement du cadre. La plupart de ces propriétés sont définies dans le service com.sun.star.text.BaseFrameProperties, également pris en charge par chaque service TextFrame. Les propriétés centrales sont les suivantes :
- BackColor (Long)
- couleur d'arrière-plan du cadre texte.
- BottomMargin (Long)
- marge inférieure en centièmes de millimètre.
- LeftMargin (Long)
- marge gauche en centièmes de millimètre.
- RightMargin (Long)
- marge droite en centièmes de millimètre.
- TopMargin (Long)
- marge supérieure en centièmes de millimètre.
- Height (Long)
- hauteur du cadre texte en centièmes de millimètre.
- Width (Long)
- largeur du cadre texte en centièmes de millimètre.
- HoriOrient (const)
- orientation horizontale du cadre texte (correspondant à com.sun.star.text.HoriOrientation).
- VertOrient (const)
- orientation verticale du cadre texte (correspondant à com.sun.star.text.VertOrientation).
L'exemple suivant crée un cadre texte à l'aide des propriétés ci-dessus :
Dim Doc As Object Dim TextTables As Object Dim Cursor As Object Dim Frame As Object Doc = StarDesktop.CurrentComponent Cursor = Doc.Text.createTextCursor() Cursor.gotoNextWord(False) Frame = Doc.createInstance("com.sun.star.text.TextFrame") Frame.Width = 3000 Frame.Height = 1000 Frame.AnchorType = com.sun.star.text.TextContentAnchorType.AS_CHARACTER Frame.TopMargin = 0 Frame.BottomMargin = 0 Frame.LeftMargin = 0 Frame.RightMargin = 0 Frame.BorderDistance = 0 Frame.HoriOrient = com.sun.star.text.HoriOrientation.NONE Frame.VertOrient = com.sun.star.text.VertOrientation.LINE_TOP Doc.Text.insertTextContent(Cursor, Frame, False)
Un objet TextCursor est créé pour servir de marque d'insertion pour le cadre texte. Ce dernier est positionné entre le premier et le deuxième mot du texte. Le cadre texte est créé à l'aide de Doc.createInstance. Les propriétés des objets TextFrame sont définies sur les valeurs initiales nécessaires.
Il convient de noter ici l'interaction entre les propriétés AnchorType (du service TextContent) et VertOrient (du service BaseFrameProperties). AnchorType reçoit la valeur AS_CHARACTER. Le cadre texte est donc inséré directement dans l'enchaînement et se comporte comme un caractère. Il peut ainsi être déplacé à la ligne suivante en cas de retour à la ligne, par exemple. La valeur LINE_TOP de la propriété VertOrient garantit que le bord supérieur du cadre texte se trouve à la même hauteur que le bord supérieur du caractère.
Une fois l'initialisation terminée, le cadre texte est finalement inséré dans le document texte à l'aide d'un appel de la méthode insertTextContent.
Pour éditer le contenu d'un cadre texte, l'utilisateur fait appel à l'objet TextCursor, déjà mentionné à de nombreuses reprises et également disponible pour les cadres texte.
Dim Doc As Object Dim TextTables As Object Dim Cursor As Object Dim Frame As Object Dim FrameCursor As Object Doc = StarDesktop.CurrentComponent Cursor = Doc.Text.createTextCursor() Frame = Doc.createInstance("com.sun.star.text.TextFrame") Frame.Width = 3000 Frame.Height = 1000 Doc.Text.insertTextContent(Cursor, Frame, False) FrameCursor = Frame.createTextCursor() FrameCursor.charWeight = com.sun.star.awt.FontWeight.BOLD FrameCursor.paraAdjust = com.sun.star.style.ParagraphAdjust.CENTER FrameCursor.String = "This is a small Test!"
Cet exemple crée un cadre texte, l'insère dans le document actif et ouvre un objet TextCursor pour le cadre. Ce curseur est utilisé pour définir en gras la police du cadre et centrer le paragraphe. Enfin, la chaîne "This is a small Test!" est assignée au cadre texte.
Champs de texte
Les champs de texte sont des objets TextContent, car ils ajoutent une extension logique au-delà du texte pur. Vous pouvez insérer des champs de texte dans un document texte à l'aide des mêmes méthodes que pour les autres objets TextContent :
Dim Doc As Object Dim DateTimeField As Object Dim Cursor As Object Doc = StarDesktop.CurrentComponent Cursor = Doc.Text.createTextCursor() DateTimeField = Doc.createInstance("com.sun.star.text.TextField.DateTime") DateTimeField.IsFixed = False DateTimeField.IsDate = True Doc.Text.insertTextContent(Cursor, DateTimeField, False)
Cet exemple insère un champ de texte correspondant à la date du jour au début du document texte actif. Si la valeur True est affectée à la propriété IsDate, seule la date s'affiche, sans l'heure. Si la valeur False est affectée à IsFixed, la date est actualisée automatiquement à l'ouverture du document.
Dans les anciennes versions de Apache OpenOffice, on accédait aux champs de texte par tout un ensemble de méthodes disponibles dans l'objet Selection (InsertField, DeleteUserField, SetCurField), par exemple).
Dans Apache OpenOffice 2.x, les champs sont administrés à l'aide d'un concept orienté objet. Pour créer un champ de texte particulier, il faut d'abord créer un champ de texte du type requis et l'initialiser avec les propriétés adéquates. Ce champ de texte est ensuite inséré dans le document à l'aide de la méthode insertTextContent. Un texte source correspondant est illustré dans l'exemple précédent. Les principaux types de champ et leurs propriétés sont décrits dans les sections suivantes.
Outre l'insertion de champs de texte, la recherche des champs dans un document peut également être une tâche fastidieuse. L'exemple suivant illustre le parcours de tous les champs de texte d'un document texte dans une boucle et le contrôle de leur type.
Dim Doc As Object Dim TextFieldEnum As Object Dim TextField As Object Dim I As Integer Doc = StarDesktop.CurrentComponent TextFieldEnum = Doc.getTextFields.createEnumeration While TextFieldEnum.hasMoreElements() TextField = TextFieldEnum.nextElement() If TextField.supportsService("com.sun.star.text.TextField.DateTime") Then MsgBox "Date/time" ElseIf TextField.supportsService("com.sun.star.text.TextField.Annotation") Then MsgBox "Annotation" Else MsgBox "unknown" End If Wend
La détermination des champs de texte présents se base sur la liste TextFields de l'objet Document. L'exemple crée un objet Enumeration en fonction de cette liste. Cet objet permet d'interroger successivement tous les champs de texte dans une boucle. À l'aide de la méthode supportsService, l'exemple vérifie ensuite le service pris en charge par chaque champ de texte trouvé. Si le champ s'avère être un champ de date/heure ou une annotation, le type de champ correspondant s'affiche dans une boîte d'information. S'il s'agit d'un autre champ, l'exemple affiche l'information "unknown".
La liste ci-dessous répertorie les champs de texte les plus importants et les propriétés associées. Une liste complète de tous les champs de texte est fournie dans le module com.sun.star.text.TextField de la référence de l'API. (Lorsque vous répertoriez le nom du service d'un champ de texte, des majuscules et des minuscules doivent être utilisées dans Apache OpenOffice Basic, comme dans l'exemple précédent.)
Nombre de pages, de mots et de caractères
Les champs de texte :
- com.sun.star.text.TextField.PageCount
- com.sun.star.text.TextField.WordCount
- com.sun.star.text.TextField.CharacterCount
retournent respectivement le nombre de pages, de mots ou de caractères d'un texte. Ils prennent en charge la propriété suivante :
- NumberingType (const)
- format de numérotation (constantes correspondant à com.sun.star.style.NumberingType).
Page active
Le numéro de la page active peut être inséré dans un document à l'aide du champ de texte com.sun.star.text.TextField.PageNumber. Vous pouvez spécifier les propriétés suivantes :
- NumberingType (const)
- format de numérotation (constantes correspondant à com.sun.star.style.NumberingType).
- Offset (short)
- décalage ajouté au nombre de pages (ce nombre peut être négatif).
L'exemple suivant illustre l'insertion du nombre de pages dans le pied de page d'un document.
Dim Doc As Object Dim DateTimeField As Object Dim PageStyles As Object Dim StdPage As Object Dim FooterCursor As Object Dim PageNumber As Object Doc = StarDesktop.CurrentComponent PageNumber = Doc.createInstance("com.sun.star.text.TextField.PageNumber") PageNumber.NumberingType = com.sun.star.style.NumberingType.ARABIC PageStyles = Doc.StyleFamilies.getByName("PageStyles") StdPage = PageStyles("Default") StdPage.FooterIsOn = True FooterCursor = StdPage.FooterTextLeft.Text.createTextCursor() StdPage.FooterTextLeft.Text.insertTextContent(FooterCursor, PageNumber, False)
Tout d'abord, un champ de texte prenant en charge le service com.sun.star.text.TextField.PageNumber est créé. Les lignes d'en-tête et de pied de page étant définies à l'intérieur des modèles de page de Apache OpenOffice, elles sont initialement établies à l'aide de la liste de tous les objets PageStyles.
Pour garantir que la ligne du pied de page est visible, la propriété FooterIsOn est définie sur True. Le champ de texte est alors inséré dans le document à l'aide de l'objet Text associé de la ligne de pied de page gauche.
Annotations
Dans le texte, les champs d'annotation (com.sun.star.text.TextField.Annotation) sont repérables à un petit symbole jaune. Si vous cliquez sur ce symbole, un champ de texte s'ouvre pour vous permettre d'enregistrer un commentaire à cet emplacement du texte. Un champ d'annotation présente les propriétés suivantes.
- Author (String)
- nom de l'auteur.
- Content (String)
- texte du commentaire.
- Date (Date)
- date à laquelle a été écrite l'annotation.
Date / Heure
Un champ de date/heure (com.sun.star.text.TextField.DateTime) représente la date du jour ou l'heure qu'il est. Il prend en charge les propriétés suivantes :
- IsFixed (Boolean)
- si cette propriété est définie sur True, l'heure de l'insertion reste inchangée ; si elle est défini sur False, l'heure de l'insertion est actualisée à chaque ouverture du document.
- IsDate (Boolean)
- si cette propriété est définie sur True, le champ affiche la date du jour. Dans le cas contraire, il affiche l'heure actuelle.
- DateTimeValue (struct)
- contenu actuel du champ (structure com.sun.star.util.DateTime).
- NumberFormat (const)
- format dans lequel la date ou l'heure est décrite.
Nom / Numéro de chapitre
Le nom du chapitre actif est accessible à l'aide d'un champ de texte du type com.sun.star.text.TextField.Chapter. Sa forme peut être définie à l'aide de deux propriétés.
- ChapterFormat (const)
- définit si l'élément représenté est le nom du chapitre ou son numéro (correspondant à com.sun.star.text.ChapterFormat).
- Level (Integer)
- détermine le niveau du chapitre dont le nom et/ou le numéro est affiché. La valeur 0 représente le plus haut niveau disponible.
Repères de texte
Les repères de texte (service com.sun.star.text.Bookmark) sont des objets TextContent. Leur création et leur insertion fait appel à un concept déjà décrit plus haut :
Dim Doc As Object Dim Bookmark As Object Dim Cursor As Object Doc = StarDesktop.CurrentComponent Cursor = Doc.Text.createTextCursor() Bookmark = Doc.createInstance("com.sun.star.text.Bookmark") Bookmark.Name = "My bookmarks" Doc.Text.insertTextContent(Cursor, Bookmark, True)
L'exemple crée un objet Cursor, qui marque la position d'insertion du repère de texte, puis crée l'objet repère de texte proprement dit (Bookmark). Un nom est ensuite assigné au repère de texte et ce dernier est inséré à l'emplacement du curseur dans le document, par la méthode insertTextContent.
Les repères de texte d'un texte sont accessibles par une liste appelée Bookmarks. Il est possible d'accéder aux repères de texte par leur numéro ou par leur nom.
L'exemple suivant illustre la recherche d'un repère de texte à l'intérieur d'un texte et l'insertion du texte à son emplacement.
Dim Doc As Object Dim Bookmark As Object Dim Cursor As Object Doc = StarDesktop.CurrentComponent Bookmark = Doc.Bookmarks.getByName("My bookmarks") Cursor = Doc.Text.createTextCursorByRange(Bookmark.Anchor) Cursor.String = "Here is the bookmark"
Dans cet exemple, la méthode getByName est utilisée pour trouver le repère de texte requis au moyen de son nom. L'appel createTextCursorByRange crée ensuite un objet Cursor, qui est placé à la position d'ancrage du repère de texte. Le curseur insère alors le texte requis à cet endroit.
Content on this page is licensed under the Public Documentation License (PDL). |