StarDesktop

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

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

  • Le service com.sun.star.frame.Desktop, qui est similaire au service de base de Apache OpenOffice, fournit les fonctions de l'objet Frame de Apache OpenOffice, 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 Document individuels. Il fournit les méthodes d'enregistrement, d'export et d'impression des documents.

Le service com.sun.star.frame.Desktop est créé automatiquement au démarrage de Apache OpenOffice. Ce service est accessible dans Apache OpenOffice Basic à l'aide 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, où 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 Apache OpenOffice. Le nom StarDesktop a toutefois été retenu pour l'objet Frame de Apache OpenOffice, car il indique clairement qu'il s'agit d'un objet de base pour l'intégralité de l'application.

L'objet StarDesktop remplace l'objet Application de StarOffice 5 qui s'appliquait auparavant comme un objet racine. 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 Apache OpenOffice (par exemple, FullScreen, FunctionBarVisible, Height, Width, Top, Visible) ne sont plus utilisées.

Documentation note.png On accède au document actif via Application.ActiveDocument sous Word et via Application.ActiveWorkbook, sous Excel, tandis que, dans Apache OpenOffice, c'est StarDesktop qui se charge de cette tâche. L'objet Document actif est accessible dans Apache OpenOffice via la propriété StarDesktop.CurrentComponent ou via ThisComponent.

ThisComponent

En général, ThisComponent retourne le même objet que StarDesktop.CurrentComponent, avec un avantage important. En cas d'exécution à partir de l'EDI Basic et lors du débogage ou de l'exploration, StarDesktop retourne l'EDI Basic lui-même. Il est peu probable que cela corresponde à ce que vous souhaitez obtenir. ThisComponent retourne le dernier document actif.

Informations élémentaires sur les documents dans Apache OpenOffice

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

Noms de fichier en notation URL

Comme Apache OpenOffice 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 barre oblique et non une barre oblique inverse comme sous Windows. Le chemin suivant fait référence au fichier test.odt dans le répertoire doc sur l'unité C.

file:///C:/doc/test.odt

Pour assurer la conversion des noms de fichier locaux en URL, Apache OpenOffice fournit la fonction ConvertToUrl. Pour assurer la conversion d'un URL en nom de fichier local, Apache OpenOffice fournit la fonction ConvertFromUrl :

MsgBox ConvertToUrl("C:\doc\test.odt") 
  ' supplies file:///C:/doc/test.odt
MsgBox ConvertFromUrl("file:///C:/doc/test.odt")    
  '  supplies (under Windows) c:\doc\test.odt

Dans cet exemple, un nom de fichier local est converti en URL et affiché dans une boîte de message. L'URL est ensuite converti en nom de fichier local et le résultat s'affiche.

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 valeurs hexadécimales 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

Apache OpenOffice fait appel à un format de fichier basé sur le langage XML. En utilisant XML, vous pouvez ouvrir et éditer des fichiers à l'aide 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 Apache OpenOffice les compresse et les 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)

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

En tant que deuxième paramètre, loadComponentFromURL attend un nom pour l'objet Frame de la fenêtre que Apache OpenOffice crée en interne pour son administration. Le nom prédéfini _blank est généralement utilisé à ce stade et indique à Apache OpenOffice 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 Apache OpenOffice à l'aide de ces paramètres, puisque des substituants (des valeurs factices) peuvent être attribués aux deux derniers paramètres :

Dim Doc As Object
Dim Url As String
Dim Dummy() 'It is an (empty) array of PropertyValues
 
Url = "file:///C:/test.odt"
 
Doc = StarDesktop.loadComponentFromURL(Url, "_blank", 0, Dummy)

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

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

Documentation note.png StarDesktop.loadComponentFromURL remplace les méthodes Documents.Add et Documents.Open de l'ancienne API Apache OpenOffice.

Remplacement du contenu de la fenêtre du document

Les valeurs _blank et _hidden du paramètre Frame indiquent à Apache OpenOffice 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. La constante correspondante de SearchFlags est :

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

L'exemple ci-dessous illustre le remplacement du 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.odt"
Doc = StarDesktop.loadComponentFromURL(Url, "MyFrame", SearchFlags, Dummy)
MsgBox "Press OK to display the second document."
 
Url = "file:///C:/test2.odt"
Doc = StarDesktop.loadComponentFromURL(Url, "MyFrame", _
      SearchFlags, Dummy)

Tout d'abord, le fichier test.odt est ouvert 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.odt.

Options de la méthode loadComponentFromURL

Le quatrième paramètre de la fonction loadComponentFromURL est un champ de données PropertyValue qui fournit à Apache OpenOffice 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 la 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)
à l'ouverture d'un document, le programme passe à la position définie dans JumpMark.
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 illustre l'ouverture d'un fichier texte de données séparées par des virgules dans Apache OpenOffice Calc à l'aide de l'option FilterName.

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 ({{OOo}} 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 Apache OpenOffice doit utiliser un filtre de texte Apache OpenOffice Calc pour ouvrir les fichiers.

Création de documents

Apache OpenOffice crée automatiquement un document si celui qui est 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 Apache OpenOffice Writer vide.

Objets Document

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

Enregistrement et export de documents

Les documents Apache OpenOffice 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é assigné au document. Ce n'est pas le cas des nouveaux documents. Dans ce cas, la méthode storeAsURL est utilisée. 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.odt"
Doc.storeAsURL(URL, Dummy())

Outre les méthodes ci-dessus, com.sun.star.frame.XStorable fournit également des 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 ne soit 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 à l'aide de la méthode storeAsURL. Elles déterminent la procédure qu'utilise Apache OpenOffice pour l'enregistrement d'un document. storeAsURL fournit 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 illustre l'utilisation de 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
' ... Initialize Doc 
 
Url = "file:///c:/test3.odt"
FileProperties(0).Name = "Overwrite"
FileProperties(0).Value = True
Doc.storeAsURL(sUrl, mFileProperties())

L'objet Doc est ensuite enregistré 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 factice est un champ de données PropertyValue permettant à Apache OpenOffice de spécifier plusieurs options d'impression.

Options de la méthode print

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

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 illustre l'impression de 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

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

Name (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 le changement d'imprimante et la définition du 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   ' corresponds to 20 cm
PaperSize.Height = 20000   ' corresponds to 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, l'exemple crée un champ de données pour deux entrées PropertyValue nommé PrinterProperties. Ce champ de données 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.

Content on this page is licensed under the Public Documentation License (PDL).
Personal tools