Chapitre 5 Utilisation de documents StarOffice

La structure de l'API StarOffice est telle que vous pouvez utiliser les parties de votre choix pour réaliser différentes tâches. Elle comprend les interfaces et services de création, ouverture, enregistrement, conversion et impression de documents ainsi que d'administration de modèles. Étant donné que ces zones de fonction sont disponibles dans tous les types de documents, elles sont expliquées en premier dans ce chapitre.

StarDesktop

Lors de l'utilisation de documents, deux services sont fréquemment utilisés :

• Le service com.sun.star.frame.Desktop, qui est similaire au service noyau de StarOffice et fournit les fonctions de l'objet Frame de StarOffice, sous lequel sont classées toutes les fenêtres de document. Ce service permet également de créer, d'ouvrir et d'importer des documents.

• Le service com.sun.star.document.OfficeDocument permet d'effectuer les principales opérations liées aux objets individuels de type Document. Il fournit les méthodes d'enregistrement, d'export et d'impression des documents.

Le service com.sun.star.frame.Desktop s'ouvre automatiquement au démarrage de StarOffice. Pour cela, StarOffice crée un objet accessible par saisie du nom global StarDesktop.

com.sun.star.frame.XComponentLoader est l'interface principale de StarDesktop. Elle englobe essentiellement la méthode loadComponentFromURL, qui permet la création, l'import et l'ouverture de documents.

Le nom de l'objet StarDesktop provient de StarOffice 5, dans laquelle toutes les fenêtres de document étaient intégrées dans une même application appelée StarDesktop. Le terme StarDesktop n'apparaît plus dans la version actuelle de StarOffice. Il a toutefois été retenu pour l'objet Frame de StarOffice, car il indique clairement qu'il s'agit d'un objet Basic pour l'intégralité de l'application.

L'objet StarDesktop assume la position de successeur de l'objet Application de StarOffice 5 qui s'appliquait auparavant comme un objet Root. Cependant, contrairement à l'ancien objet Application, il permet principalement d'ouvrir des documents. Les fonctions de l'ancien objet Application pour l'affichage à l'écran de StarOffice (par exemple, FullScreen, FunctionBarVisible, Height, Width, Top, Visible) ne sont plus utilisées.

---

Remarque –

Alors qu'on accède au document actif via Application.ActiveDocument sous Word et via Application.ActiveWorkbook sous Excel, dans StarOffice, c'est StarDesktop qui se charge de cette tâche. L'objet Document actif est accessible dans StarOffice 7 via la propriété StarDesktop.CurrentComponent.

---

Informations élémentaires sur les documents StarOffice

Lors de l'utilisation de documents StarOffice, il est très utile de pouvoir gérer les questions de base de leur administration dans StarOffice. Cela comprend la manière dont les noms de fichier sont structurés pour les documents StarOffice, ainsi que le format dans lequel les fichiers sont enregistrés.

Noms de fichier en notation URL

Comme StarOffice est une application indépendante de la plate-forme sur laquelle elle s'exécute, elle utilise la notation URL (qui est indépendante des différents systèmes d'exploitation), selon la norme Internet RFC 1738 relative aux noms de fichier. Les noms de fichier standard utilisant ce système commencent par le préfixe

file:///

suivi du chemin d'accès local. Si le nom du fichier contient des sous-répertoires, ceux-ci sont indiqués par une simple barre oblique et non une barre oblique inverse comme sous Windows. Le chemin suivant fait référence au fichier test.sxw dans le répertoire doc sur l'unité C.

file:///C:/doc/test.sxw

Pour convertir les noms de fichier locaux en URL, StarOffice dispose de la fonction ConvertToUrl. Pour convertir un URL en nom de fichier local, StarOffice dispose de la fonction ConvertFromUrl :

MsgBox ConvertToUrl("C:\doc\test.sxw")
      ' fournit file:///C:/doc/test.sxw
MsgBox ConvertFromUrl("file:///C:/doc/test.sxw")
      '  fournit (sous Windows) c:\doc\test.sxw

Cet exemple convertit un nom de fichier local en URL et l'affiche dans une boîte de message. Il convertit ensuite l'URL en nom de fichier local et affiche également le résultat.

La norme Internet RFC 1738, utilisée ici, autorise l'emploi des caractères 0 à 9, a à z et A à Z. Tous les autres caractères sont insérés dans les URL sous forme de codes d'échappement. Pour ce faire, ils sont convertis en leur valeur hexadécimale dans le jeu de caractères ISO 8859-1 (ISO-Latin) et précédés du signe de pourcentage. Un espace dans un nom de fichier local, par exemple, devient un %20 dans l'URL.

Format de fichier XML

Depuis la version 6.0, StarOffice fournit un format de fichier basé sur le langage XML. Grâce à l'emploi de XML, l'utilisateur a la possibilité d'ouvrir et d'éditer les fichiers dans d'autres programmes.

Compression de fichiers

Comme XML utilise des fichiers texte standard, les fichiers obtenus sont généralement très volumineux, c'est pourquoi StarOffice les compresse et enregistre sous forme de fichier ZIP. Grâce à une option de la méthode storeAsURL, l'utilisateur peut enregistrer directement les fichiers XML d'origine. Pour plus d'informations, consultez la section Options de la méthode storeAsURL.

Création, ouverture et import de documents

La méthode StarDesktop.loadComponentFromURL(URL, Frame, _ SearchFlags, FileProperties)

permet d'ouvrir, d'importer et de créer des documents.

Le premier paramètre de la méthode loadComponentFromURL indique l'URL du fichier associé.

Au deuxième paramètre, loadComponentFromURL attend un nom pour l'objet Frame de la fenêtre que StarOffice crée en interne pour son administration. Le nom prédéfini _blank est généralement utilisé à ce stade et indique à StarOffice de créer une fenêtre. Il est également possible de spécifier la valeur _hidden, qui permet de charger le document correspondant tout en le gardant invisible.

L'utilisateur peut ouvrir un document StarOffice avec ces seuls paramètres, car les deux derniers peuvent ne contenir que des substituants (des valeurs factices) :

Dim Doc As Object
Dim Url As String
Dim Dummy()

Url = "file:///C:/test.sxw"

Doc = StarDesktop.loadComponentFromURL(Url, "_blank", 0, Dummy())

L'appel ci-dessus ouvre le fichier text.sxw et l'affiche dans une nouvelle fenêtre.

Cette méthode permet d'ouvrir autant de documents que souhaités dans StarOffice Basic et de les éditer à l'aide des objets Document renvoyés.

---

Remarque –

StarDesktop.loadComponentFromURL remplace les méthodes Documents.Add et Documents.Open de l'ancienne API StarOffice.

---

Remplacement du contenu de la fenêtre de document

Les valeurs _blank et _hidden du paramètre Frame indiquent à StarOffice de créer une fenêtre à chaque appel de loadComponentFromURL. Il s'avère parfois utile de remplacer le contenu d'une fenêtre existante. Si tel est le cas, l'objet Frame de la fenêtre doit contenir un nom explicite. Ce nom ne doit pas commencer par un trait de soulignement. Par ailleurs, le paramètre SearchFlags doit être défini pour que la structure correspondante soit créée, si elle n'existe pas déjà. La constante correspondante de SearchFlags est :

SearchFlags = com.sun.star.frame.FrameSearchFlag.CREATE + _
         com.sun.star.frame.FrameSearchFlag.ALL

L'exemple ci-dessous indique comment remplacer le contenu d'une fenêtre ouverte à l'aide du paramètre Frame et de SearchFlags :

Dim Doc As Object
Dim Dummy()
Dim Url As String
Dim SearchFlags As Long

SearchFlags = com.sun.star.frame.FrameSearchFlag.CREATE + _
         com.sun.star.frame.FrameSearchFlag.ALL

Url = "file:///C:/test.sxw"
Doc = StarDesktop.loadComponentFromURL(Url, "MyFrame", _
      SearchFlags, Dummy)

MsgBox "Cliquez sur OK pour afficher le deuxième document."

Url = "file:///C:/test2.sxw"
Doc = StarDesktop.loadComponentFromURL(Url, "MyFrame", _
      SearchFlags, Dummy)

L'exemple commence par ouvrir le fichier test.sxw dans une nouvelle fenêtre avec le nom de cadre MyFrame. Lorsque l'utilisateur clique sur OK dans la boîte de message, le contenu de la fenêtre est remplacé par le fichier test2.sxw.

Options de la méthode loadComponentFromURL

Le quatrième paramètre de la fonction loadComponentFromURL est un champ de données PropertyValue qui fournit à StarOffice de nombreuses options d'ouverture et de création de documents. Le champ de données doit contenir une structure PropertyValue pour chaque option. Le nom de l'option y est enregistré sous forme de chaîne, tout comme sa valeur associée.

loadComponentFromURL prend en charge les options suivantes :

• AsTemplate (Boolean) : si la valeur est True, la méthode charge un nouveau document sans titre à partir de l'URL spécifié. Si la valeur est False, les fichiers de modèle sont chargés en vue de leur édition.

• CharacterSet (String) : définit le jeu de caractères utilisé par un document.

• FilterName (String) : spécifie un filtre élaboré pour la fonction loadComponentFromURL. Les noms de filtre disponibles sont définis dans le fichier \share\config\registry\instance\org\openoffice\office\TypeDetection.xml.

• FilterOptions (String) : définit les options supplémentaires pour les filtres.

• JumpMark (String) : le programme passe à la position définie dans JumpMark, une fois un document ouvert.

• Password (String) : transfère le mot de passe d'un fichier protégé.

• ReadOnly (Boolean) : charge un document en lecture seule.

L'exemple ci-dessous indique comment utiliser l'option FilterName pour ouvrir un fichier texte séparé par des virgules dans StarOffice Calc.

Dim Doc As Object
Dim FileProperties(0) As New com.sun.star.beans.PropertyValue
Dim Url As String

Url = "file:///C:/csv.doc"

FileProperties(0).Name = "FilterName"
FileProperties(0).Value ="scalc: Text - txt - csv (StarOffice Calc)"

Doc = StarDesktop.loadComponentFromURL(Url, "_blank", 0, FileProperties())

Le champ de données FileProperties englobe une seule valeur, car il contient une seule option. La propriété Filtername définit si StarOffice doit utiliser un filtre de texte StarOffice Calc pour ouvrir les fichiers.

Création de documents

StarOffice crée automatiquement un document si celui indiqué dans l'URL est un modèle.

Il est également possible de spécifier un URL private:factory si seul un document vide sans aucune adaptation est nécessaire :

Dim Dummy()
Dim Url As String
Dim Doc As Object

Url = "private:factory/swriter"
Doc = StarDesktop.loadComponentFromURL(Url, "_blank", 0, Dummy())

Cet appel crée un document StarOffice Writer vide.

Objets Document

La fonction loadComponentFromURL présentée dans la section précédente renvoie un objet Document. Elle prend en charge le service com.sun.star.document.OfficeDocument, qui fournit à son tour deux interfaces centrales :

• l'interface com.sun.star.frame.XStorable, qui permet d'enregistrer les documents ;

• l'interface com.sun.star.view.XPrintable, qui contient les méthodes nécessaires à l'impression des documents.

---

Remarque –

Si vous migrez vers StarOffice 8, vous constaterez que la portée des objets Document est restée sensiblement la même. On y retrouve, par exemple, des méthodes pour enregistrer ou imprimer des documents. Les noms et les paramètres de ces méthodes ont, en revanche, été modifiés.

---

Enregistrement et export de documents

Les documents StarOffice sont enregistrés directement via l'objet Document. La méthode store de l'interface com.sun.star.frame.XStorable a été prévue pour cela :

Doc.store()

Cet appel fonctionne à condition qu'un espace mémoire ait déjà été attribué au document. Ce n'est pas le cas des nouveaux documents. Dans cette instance, la méthode utilisée est storeAsURL. Cette méthode est également définie dans com.sun.star.frame.XStorable et peut servir à définir l'emplacement du document :

Dim URL As String
Dim Dummy()

Url = "file:///C:/test3.sxw"

Doc.storeAsURL(URL, Dummy())

Outre les méthodes ci-dessus, com.sun.star.frame.XStorable fournit également certaines méthodes d'aide utiles pour l'enregistrement de documents, à savoir :

• hasLocation() : indique si un URL a déjà été assigné au document.

• isReadonly() : indique si un document est protégé en lecture seule.

• isModified() : indique si un document a été modifié depuis son dernier enregistrement.

Le code permettant d'enregistrer un document peut être étendu par ces options pour que celui-ci ne soit enregistré que si l'objet a effectivement été modifié et que le nom de fichier n'est demandé que s'il est réellement nécessaire :

If (Doc.isModified) Then
   If (Doc.hasLocation And (Not Doc.isReadOnly)) Then
      Doc.store()
   Else
      Doc.storeAsURL(URL, Dummy())
   End If
End If

Cet exemple commence par vérifier si le document concerné a été modifié depuis son dernier enregistrement. Il ne poursuit le processus d'enregistrement que dans ce cas. Si un URL a déjà été assigné au document et s'il ne s'agit pas d'un document en lecture seule, il est enregistré sous l'URL existant. S'il ne possède pas d'URL ou s'il a été ouvert en lecture seule, il est enregistré sous un nouvel URL.

Options de la méthode storeAsURL

Tout comme avec la méthode loadComponentFromURL, certaines options peuvent être spécifiées sous forme de champ de données PropertyValue grâce à la méthode storeAsURL. Elles déterminent la procédure qu'utilise StarOffice pour l'enregistrement d'un document. storeAsURL comporte les options suivantes :

• CharacterSet (String) : définit le jeu de caractères utilisé par un document.

• FilterName (String) : spécifie un filtre élaboré pour la fonction loadComponentFromURL. Les noms de filtre disponibles sont définis dans le fichier \share\config\registry\instance\org\openoffice\office\TypeDetection.xml.

• FilterOptions (String) : définit les options supplémentaires pour les filtres.

• Overwrite (Boolean) : permet d'écraser un fichier existant sans confirmation.

• Password (String) : transfère le mot de passe d'un fichier protégé.

• Unpacked (Boolean) : enregistre le document (non compressé) dans des sous-répertoires.

L'exemple ci-dessous indique comment utiliser l'option Overwrite en conjonction avec storeAsURL :

Dim Doc As Object
Dim FileProperties(0) As New com.sun.star.beans.PropertyValue
Dim Url As String

' ... Initialiser le document

Url = "file:///c:/test3.sxw"

FileProperties(0).Name = "Overwrite"
FileProperties(0).Value = True

Doc.storeAsURL(sUrl, mFileProperties())

L'exemple enregistre ensuite le Document sous le nom de fichier spécifié si un fichier existant porte déjà ce nom.

Impression de documents

Tout comme pour l'enregistrement, les documents sont imprimés directement à l'aide de l'objet Document. La méthode Print de l'interface com.sun.star.view.Xprintable est fournie à cet effet : Sous sa forme la plus simple, l'appel de print est le suivant :

Dim Dummy()

Doc.print(Dummy())

Comme pour la méthode loadComponentFromURL, le paramètre Dummy est un champ de données PropertyValue permettant à StarOffice de spécifier plusieurs options d'impression.

Options de la méthode print

La méthode print attend en argument un champ de données PropertyValue correspondant au paramétrage de la boîte de dialogue d'impression de StarOffice :

• CopyCount (Integer) : indique le nombre d'exemplaires à imprimer.

• FileName (String) : imprime le document dans le fichier spécifié.

• Collate (Boolean) : indique à l'imprimante qu'elle doit rassembler les pages de chaque exemplaire.

• Sort (Boolean) : trie les pages lors de l'impression de plusieurs exemplaires (CopyCount > 1).

• Pages (String) : contient la liste des pages à imprimer (selon la syntaxe spécifiée dans la boîte de dialogue d'impression).

L'exemple suivant indique comment imprimer plusieurs pages d'un document à l'aide de l'option Pages :

Dim Doc As Object
Dim PrintProperties(0) As New com.sun.star.beans.PropertyValue

PrintProperties(0).Name="Pages"
PrintProperties(0).Value="1-3; 7; 9"

Doc.print(PrintProperties())

Sélection et paramétrage de l'imprimante

L'interface com.sun.star.view.XPrintable fournit la propriété Printer, qui permet de sélectionner l'imprimante. Cette propriété reçoit un champ de données PropertyValue avec les paramètres suivants :

• Na,e (String) : indique le nom de l'imprimante.

• PaperOrientation (Enum) : indique l'orientation du papier (valeur com.sun.star.view.PaperOrientation.PORTRAIT pour l'orientation portrait, com.sun.star.view.PaperOrientation.LANDSCAPE pour l'orientation paysage).

• PaperFormat (Enum) : indique le format du papier (com.sun.star.view.PaperFormat.A4 pour le format DIN A4 ou com.sun.star.view.PaperFormat.Letter pour le format US Letter, par exemple).

• PaperSize (Size) : indique la taille du papier en centièmes de millimètre.

L'exemple suivant illustre comment changer d'imprimante et définir le format du papier à l'aide de la propriété Printer.

Dim Doc As Object
Dim PrinterProperties(1) As New com.sun.star.beans.PropertyValue
Dim PaperSize As New com.sun.star.awt.Size


PaperSize.Width = 20000   ' correspond à 20 cm
PaperSize.Height = 20000   ' correspond à 20 cm

PrinterProperties (0).Name="Name"
PrinterProperties (0).Value="My HP Laserjet"

PrinterProperties (1).Name="PaperSize"
PrinterProperties (1).Value=PaperSize

Doc.Printer = PrinterProperties()

L'exemple définit un objet nommé PaperSize avec le type com.sun.star.awt.Size. Cet objet est nécessaire pour spécifier le format de papier. De plus, il crée un champ de données pour deux entrées PropertyValue nommé PrinterProperties. Il est ensuite initialisé avec les valeurs à définir et assigné à la propriété Printer. Du point de vue d'UNO, l'imprimante n'est pas une propriété réelle, mais en imite une.

Modèles

Les modèles sont des listes nommées contenant des attributs de formatage. Ils couvrent toutes les applications de StarOffice et permettent de simplifier considérablement le formatage. Si l'utilisateur modifie l'un des attributs d'un modèle, StarOffice modifie automatiquement toutes les sections du document en fonction de l'attribut. L'utilisateur peut donc, par exemple, modifier le type de police de tous les titres de niveau un via une modification centrale dans le document. Selon le type de documents, StarOffice reconnaît toute une gamme de types de modèles différents.

StarOffice Writer prend en charge

• les modèles de caractère ;

• les modèles de paragraphe ;

• les modèles de cadre ;

• les modèles de page ;

• les modèles de numérotation.

StarOffice Calc prend en charge

• les modèles de cellule ;

• les modèles de page.

StarOffice Impress prend en charge

• les modèles d'élément de caractères ;

• les modèles de présentation.

Dans la terminologie de StarOffice, les différents types de modèles sont appelés StyleFamilies selon le service com.sun.star.style.StyleFamily sur lequel ils sont basés. Les objets StyleFamilies sont accessibles depuis l'objet Document :

Dim Doc As Object
Dim Sheet As Object
Dim StyleFamilies As Object
Dim CellStyles As Object

Doc = StarDesktop.CurrentComponent
StyleFamilies = Doc.StyleFamilies
CellStyles = StyleFamilies.getByName("CellStyles")

Cet exemple utilise la propriété StyleFamilies d'un classeur pour établir une liste de tous les modèles de cellules disponibles.

Il est possible d'accéder séparément à chaque modèle au moyen d'un index :

Dim Doc As Object
Dim Sheet As Object
Dim StyleFamilies As Object
Dim CellStyles As Object
Dim CellStyle As Object
Dim I As Integer

Doc = StarDesktop.CurrentComponent
StyleFamilies = Doc.StyleFamilies
CellStyles = StyleFamilies.getByName("CellStyles")

For I = 0 To CellStyles.Count - 1
   CellStyle = CellStyles(I)
   MsgBox CellStyle.Name
Next I

La boucle ajoutée depuis l'exemple précédent affiche successivement les noms de tous les modèles de cellule dans une boîte de message.

Informations relatives à diverses options de formatage

Chaque type de modèle comporte une gamme complète de propriétés individuelles de formatage. Les principales propriétés de formatage sont expliquées aux emplacements suivants :

• section Propriétés de caractère du chapitre 6 (Documents texte), servicecom.sun.star.style.CharacterProperties ;

• section Propriétés de paragraphe du chapitre 6 (Documents texte), service com.sun.star.text.Paragraph ;

• section Propriétés de cellule du chapitre 7 (Classeurs), service com.sun.star.table.CellProperties ;

• section Propriétés de page du chapitre 7 (Classeurs), service com.sun.star.style.PageStyle ;

• section Propriétés d'élément de caractère du chapitre 7 (Classeurs), services divers.

Les propriétés de format ne se limitent en aucun cas aux applications dans lesquelles elles sont expliquées et peuvent être utilisées universellement. La plupart des propriétés de page décrites au Chapitre 7, Classeurs peuvent par exemple être utilisées non seulement dans StarOffice Calc, mais également dans StarOffice Writer.

Pour plus d'informations sur l'utilisation de modèles, consultez la section Valeurs par défaut des propriétés de caractère et de paragraphe du Chapitre 6, Documents texte.