SFDocuments.Document service

La bibliothèque SFDocuments fournit des méthodes et des propriétés pour faciliter la gestion et la manipulation des documents LibreOffice.

Les méthodes applicables à tous les types de documents (Documents Textes, Classeurs, Présentations, etc.) sont fournies par le service SFDocuments.Document. Certains exemples sont :

warning

Les propriétés, méthodes ou arguments marqués d'un (*) ne sont PAS applicables aux documents Base.


Les méthodes et propriétés spécifiques à certains composants LibreOffice sont stockées dans des services distincts, tels que SFDocuments.SF_Calc et SFDocuments.SF_Base.

Bien que le langage Basic ne propose pas d'héritage entre classes d'objets, ces derniers services peuvent être considérés comme des sous-classes du service SFDocuments.Document. Ces sous-classes peuvent invoquer les propriétés et les méthodes décrites ci-dessous.

Invocation du service

Avant d'utiliser le service Document, la bibliothèque ScriptForge doit être chargée ou importée :

note

• Les macros Basic nécessitent de charger la bibliothèque ScriptForge à l'aide de l'instruction suivante :
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Les scripts Python nécessitent un import depuis le module scriptforge :
from scriptforge import CreateScriptService


Vous trouverez ci-dessous trois variantes de la façon dont le service Document peut être appelé.

En Basic :

Utilisation de la méthode getDocument du service ScriptForge.UI :


    Dim ui As Object, oDoc As Object
    Set ui = CreateScriptService("UI")
    Set oDoc = ui.GetDocument("Untitled 1")
  

Vous pouvez également utiliser les méthodes CreateDocument et OpenDocument du service UI.


    Set oDocA = ui.CreateDocument("Calc")
    Set oDocB = ui.OpenDocument("C:\Documents\MyFile.odt")
  

Directly if the document is already open.


    Dim oDoc As Object
    Set oDoc = CreateScriptService("SFDocuments.Document", "Untitled 1") 'Default = ActiveWindow
  

À partir d'une macro déclenchée par un événement de document.


    Sub RunEvent(ByRef poEvent As Object)
        Dim oDoc As Object
        Set oDoc = CreateScriptService("SFDocuments.DocumentEvent", poEvent)
        ' (...)
    End Sub
  
note

Le service Document est étroitement lié aux services UI et FileSystem.


Sauf lorsque le document a été fermé par programme avec la méthode CloseDocument (c'est alors superflu), il est recommandé de libérer des ressources après utilisation :


    Set oDoc = oDoc.Dispose()
  
En Python

    from scriptforge import CreateScriptService
    ui = CreateScriptService("UI")
    doc = ui.GetDocument("Untitled 1")
    # (...)
    doc.Dispose()
  

    docA = ui.CreateDocument("Calc")
    docB = ui.OpenDocument("C:\Documents\MyFile.odt")
  

    doc = CreateScriptService("SFDocuments.Document", "Untitled 1")
  

    def RunEvent(event)
        doc = CreateScriptService("SFDocuments.DocumentEvent", Event)
        # (...)
  
tip

L'utilisation du préfixe "SFDocuments." lors de l'appel du service est facultative.


Propriétés

Nom

En lecture seule

Type

Description

CustomProperties (*)

Non

Dictionary service

Returns a ScriptForge.Dictionary object instance. After update, can be passed again to the property for updating the document.
Individual items of the dictionary may be either strings, numbers, (Basic) dates or com.sun.star.util.Duration items.

Description (*)

Non

String

Donne accès à la propriété Description du document (également appelée "Comments")

DocumentProperties (*)

Oui

Dictionary service

Renvoie un objet ScriptForge.Dictionary contenant toutes les entrées. Les statistiques du document sont incluses. Notez qu'elles sont spécifiques au type de document. Par exemple, un document Calc inclut une entrée "CellCount". D'autres documents ne les ont pas.

DocumentType

Oui

String

Valeur de chaîne avec le type de document ("Base", "Calc", "Writer", etc.)

ExportFilters

Oui

String array

Renvoie une liste avec les noms de filtres d'export applicables au document actuel sous la forme d'une matrice de chaînes de base zéro. Les filtres utilisés pour l'import/export sont également renvoyés.

ImportFilters

Oui

String array

Renvoie une liste avec les noms de filtres d'import applicables au document actuel sous la forme d'une matrice de chaînes de base zéro. Les filtres utilisés pour l'import/export sont également renvoyés.

IsBase
IsCalc
IsDraw
IsImpress
IsMath
IsWriter

Oui

Boolean

Exactement une de ces propriétés est True pour un document donné.

Keywords (*)

Non

String

Donne accès à la propriété Keywords du document. Représenté sous la forme d'une liste de mots-clés séparés par des virgules

Readonly (*)

Oui

Boolean

True si le document est réellement en mode lecture seule

Subject (*)

Non

String

Donne accès à la propriété Subject du document.

Title (*)

Non

String

Donne accès à la propriété Title du document.

XComponent

Oui

Objets UNO

The UNO object com.sun.star.lang.XComponent or com.sun.star.comp.dba.ODatabaseDocument representing the document


Exemple :

En Basic :

L'exemple ci-dessous imprime toutes les propriétés d'un document. Notez que l'objet oDoc renvoyé par la méthode UI.OpenDocument est un objet SFDocuments.Document.


    Dim ui as Variant : Set ui = CreateScriptService("UI")
    Dim oDoc as Object
    Set oDoc = ui.OpenDocument("C:\Documents\MyFile.ods")
    Dim propDict as Object
    Set propDict = oDoc.DocumentProperties
    Dim keys as Variant : propKeys = propDict.Keys
    Dim k as String, strProp as String
    For Each k In propKeys
        strProp = strProp & k & ": " & propDict.Item(k) & CHR$(10)
    Next k
    MsgBox strProp
    oDoc.CloseDocument()
  
En Python

Pour accéder aux propriétés du document dans un script Python, l'utilisateur doit y accéder directement en utilisant leurs noms, comme indiqué ci-dessous :


    doc = ui.GetDocument(r"C:\Documents\MyFile.ods")
    msg = doc.Title + '\n' + doc.Description + '\n' + doc.Keywords
    bas = CreateScriptService("Basic")
    bas.MsgBox(msg)
    doc.CloseDocument()
  

Liste des méthodes dans le service Document

Activate
CloseDocument
CreateMenu
ExportAsPDF

PrintOut
RemoveMenu
RunCommand
Save

SaveAs
SaveCopyAs
SetPrinter


Activate

Renvoie True si le document peut être activé. Sinon, il n'y a aucun changement dans l'interface utilisateur active. Elle est équivalente à la méthode Activate du service UI.

Cette méthode est utile lorsque l'on doit donner le focus à un document réduit ou masqué.

Syntaxe :

svc.Activate(): bool

Exemple :

L'exemple ci-dessous considère que le fichier "My_File.ods" est déjà ouvert mais pas actif.

En Basic :

    Dim oDoc As Object
    Set oDoc = CreateScriptService("Document", "MyFile.ods")
    oDoc.Activate()
  
En Python

    doc = CreateScriptService("Document", "MyFile.ods")
    doc.Activate()
  
tip

Gardez à l'esprit que vous pouvez invoquer le service Document en passant à CreateScriptService "Document" ou "SFDocuments.Document"


CloseDocument

Ferme le document. Si le document est déjà fermé, quelle que soit la façon dont le document a été fermé, cette méthode n'a aucun effet et renvoie False.

La méthode renverra également False si l'utilisateur refuse de le fermer.

Renvoie True si le document a été fermé avec succès.

Syntaxe :

svc.CloseDocument(saveask: bool = True): bool

Paramètres :

saveask : si True (par défaut), l'utilisateur est invité à confirmer si les modifications doivent être écrites sur le disque. Cet argument est ignoré si le document n'a pas été modifié.

Exemple :

En Basic :

    If oDoc.CloseDocument(True) Then
        ' ...
    End If
  
En Python

    if doc.CloseDocument(True):
        # ...
  

CreateMenu

Crée une nouvelle entrée de menu dans la barre de menus d'une fenêtre de document donnée.

This method returns an instance of the SFWidgets.Menu service.

note

Le menu créé n'est disponible que pendant la session LibreOffice en cours et n'est enregistré ni dans le document ni dans les paramètres globaux de l'application. Par conséquent, la fermeture de la fenêtre du document fera disparaître le menu. Il ne réapparaîtra que lorsque la macro qui crée le menu sera à nouveau exécutée.


Syntaxe :

svc.CreateMenu(menuheader: str, [before: any], submenuchar: str = ">"): svc

Paramètres :

menuheader : le nom de niveau supérieur du nouveau menu.

before : Le nom (sous forme de chaîne) ou la position (sous forme d'entier commençant à 1) d'un menu existant avant lequel le nouveau menu sera placé. Si aucune valeur n'est définie pour cet argument, le menu sera créé à la dernière position dans la barre de menus.

submenuchar : le délimiteur utilisé pour créer des arborescences de menus lors de l'appel de méthodes en tant que AddItem à partir du service Menu. La valeur par défaut est ">".

Exemple :

En Basic :

    Dim oDoc as Object, oMenu as Object
    Set oDoc = CreateScriptService("Document")
    Set oMenu = oDoc.CreateMenu("My Menu")
    With oMenu
        'Ajoute un élément au menu
        .AddItem("Item A")
        .AddItem("Item B")
        ' ...
        ' Après avoir créé le menu, l'instance de service peut être supprimée
        .Dispose()
    End With
  
En Python

    doc = CreateScriptService("Document")
    menu = doc.CreateMenu("My Menu")
    menu.AddItem("Item A")
    menu.AddItem("Item B")
    # ...
    menu.Dispose()
  
tip

Refer to the SFWidgets.Menu help page to learn more about how to create/remove menus in LibreOffice document windows.


ExportAsPDF

Exporte le document directement sous forme de fichier PDF à l'emplacement spécifié. Renvoie True si le fichier PDF a été créé avec succès.

The export options can be set either manually using the File - Export As - Export as PDF dialog or by calling the methods GetPDFExportOptions and SetPDFExportOptions from the Session service.

Syntaxe :

svc.ExportAsPDF(filename: str, overwrite: bool = False, opt pages: str, opt password: str, opt watermark: str): bool

Paramètres :

filename : chemin d'accès complet et nom de fichier du PDF à créer. Il doit suivre la notation SF_FileSystem.FileNaming.

overwrite : spécifie si le fichier de destination peut être écrasé (par défaut = False). Une erreur se produira si overwrite est défini sur False et que le fichier de destination existe déjà.

pages : chaîne spécifiant quelles pages seront exportées. Cet argument utilise la même notation que dans la boîte de dialogue Fichier - Exporter sous - Exporter au format PDF.

password : spécifie un mot de passe pour ouvrir le fichier PDF.

watermark : texte à utiliser comme filigrane dans le fichier PDF, qui sera dessiné sur chaque page du PDF résultant.

Exemple :

En Basic :

L'exemple suivant exporte le document actuel sous forme de fichier PDF, définit un mot de passe et écrase le fichier de destination s'il existe déjà.


    oDoc.ExportAsPDF("C:\User\Documents\myFile.pdf", Password := "1234", Overwrite := True)
  

L'extrait de code ci-dessous récupère les options d'export PDF actuelles et les utilise pour créer le fichier PDF.


    Dim exportSettings as Object, oSession as Object
    oSession = CreateScriptService("Session")
    exportSettings = oSession.GetPDFExportOptions()
    ' Définit sur True l'option d'export des commentaires sous forme de notes PDF
    exportSettings.ReplaceItem("ExportNotes", True)
    oSession.SetPDFExportOptions(exportSettings)
    oDoc.ExportAsPDF("C:\User\Documents\myFile.pdf")
  
En Python

    doc.ExportAsPDF(r"C:\User\Documents\myFile.pdf", password = "1234", overwrite = True)
  

    session = CreateScriptService("Session")
    exportSettings = oSession.GetPDFExportOptions()
    exportSettings.ReplaceItem("ExportNotes", True)
    session.SetPDFExportOptions(exportSettings)
    doc.ExportAsPDF(r"C:\User\Documents\myFile.pdf")
  

PrintOut

Cette méthode envoie le contenu du document à l'imprimante par défaut ou à l'imprimante définie par la méthode SetPrinter.

Renvoie True si le document a été imprimé avec succès.

Syntaxe :

svc.PrintOut(pages: str = "", copies: num = 1): bool

Paramètres :

pages : les pages à imprimer sous forme de chaîne, comme dans l'interface utilisateur. Exemple : "1-4;10;15-18". La valeur par défaut est toutes les pages.

copies : le nombre de copies. La valeur par défaut est 1.

Exemple :

En Basic :

    If oDoc.PrintOut("1-4;10;15-18", Copies := 2) Then
        ' ...
    End If
  
En Python

    if doc.PrintOut(copies=3, pages='45-88'):
        # ...
  

RemoveMenu

Supprime un menu de niveau supérieur de la barre de menus d'une fenêtre de document donnée.

Renvoie True si le menu spécifié peut être supprimé. Si le menu spécifié n'existe pas, la méthode renvoie False.

note

Cette méthode peut être utilisée pour supprimer toute entrée de menu de la fenêtre du document, y compris les menus par défaut. Cependant, aucune de ces modifications dans la barre de menus n'est enregistrée dans le document ou dans les paramètres de l'application. Pour restaurer la barre de menus aux paramètres par défaut, fermez et rouvrez simplement la fenêtre du document.


Syntaxe :

svc.RemoveMenu(menuheader: str): bool

Paramètres :

menuheader : le nom de niveau supérieur du menu à supprimer.

Exemple :

En Basic :

    Dim oDoc as Object
    Set oDoc = CreateScriptService("Document")
    oDoc.RemoveMenu("My Menu")
  
En Python

    doc = CreateScriptService("Document")
    doc.RemoveMenu("My Menu")
  
tip

Refer to the SFWidgets.Menu help page to learn more about how to create/remove menus in LibreOffice document windows.


RunCommand

Exécute une commande UNO sur la fenêtre de document associée à l'instance de service. Quelques commandes typiques sont : Save, SaveAs, ExportToPDF, Undo, Copy, Paste, etc.

Le document lui-même n'a pas besoin d'être actif pour pouvoir exécuter des commandes.

Les commandes peuvent être exécutées avec ou sans arguments. Les arguments ne sont pas validés avant l'exécution de la commande. Si la commande ou ses arguments ne sont pas valides, rien ne se passera.

tip

For a complete list of UNO commands that can be run in LibreOffice, refer to the Wiki page Development/DispatchCommands.


Syntaxe :

svc.RunCommand(command: str, [args: any])

Paramètres :

commande : chaîne sensible à la casse contenant le nom de la commande UNO. L'inclusion du préfixe ".uno :" dans la commande est facultative. L'exactitude de la commande elle-même n'est pas vérifiée. Si rien ne se passe après l'appel de la commande, la commande est probablement erronée.

args : pour chaque argument à transmettre à la commande, spécifiez une paire contenant le nom et la valeur de l'argument.

Exemple :

En Basic :

L'exemple suivant exécute la commande SelectData dans un fichier Calc nommé "MyFile.ods", ce qui entraînera la sélection de la zone de données en fonction de la cellule actuellement sélectionnée. Notez que cette commande ne nécessite aucun argument.


    Set oDoc = CreateScriptService("Document", "MyFile.ods")
    oDoc.RunCommand("SelectData")
  

Vous trouverez ci-dessous un exemple qui exécute la commande UNO ReplaceAll et transmet des valeurs pour ses arguments SearchString et ReplaceString. L'exécution de cette commande remplacera toutes les occurrences de la chaîne "abc" par "ABC" dans la feuille actuelle.


    ' Arguments passés à la commande :
    ' SearchString  = "abc"
    ' ReplaceString = "ABC"
    oDoc.RunCommand(".uno:ReplaceAll", "SearchString", "abc", "ReplaceString", "ABC")
  

Notez que l'appel de la commande ReplaceAll sans arguments ouvrira la boîte de dialogue Rechercher et remplacer.

En Python

    doc = CreateScriptService("Document", "MyFile.ods")
    doc.RunCommand("SelectData")
  

    doc.RunCommand(".uno:ReplaceAll", "SearchString", "abc", "ReplaceString", "ABC")
  

En Python, il est également possible d'appeler RunCommand en utilisant des arguments de mots-clés :


    doc.RunCommand(".uno:ReplaceAll", SearchString = "abc", ReplaceString = "ABC")
  
tip

Chaque composant LibreOffice dispose de son propre jeu de commandes. Un moyen simple d'apprendre les commandes est d'aller dans Outils - Personnaliser - Clavier. Lorsque le curseur de la souris est positionné sur une fonction dans la liste Fonction, une info-bulle apparaît avec la commande UNO correspondante.


Save

Stocke le document à l'emplacement du fichier à partir duquel il a été chargé. La méthode est ignorée si le document n'a pas été modifié.

Renvoie False si le document n'a pas pu être enregistré. Une erreur est générée si le fichier est ouvert en lecture seule ou s'il s'agit d'un nouveau fichier qui n'a pas encore été enregistré.

Le document lui-même n'a pas besoin d'être actif pour exécuter cette méthode.

Syntaxe :

svc.Save(): bool

Exemple :

En Basic :

    If Not oDoc.Save() Then
        ' ...
    End If
  
En Python

    if not doc.Save():
        # ...
  

SaveAs

Stocke le document à l'emplacement de fichier donné. Le nouvel emplacement devient le nouveau nom de fichier sur lequel les appels simples à la méthode Save seront appliqués.

Renvoie False si le document n'a pas pu être enregistré. Une erreur est générée lorsque le remplacement de la destination est rejeté ou lorsque la destination a son attribut en lecture seule défini.

Le document lui-même n'a pas besoin d'être actif pour exécuter cette méthode.

Syntaxe :

svc.SaveAs(filename: str, overwrite: bool = False, password: str = '', filtername: str = '', filteroptions: str = ''): bool

Paramètres :

filename : une chaîne contenant le nom du fichier à utiliser. Il doit suivre la notation SF_FileSystem.FileNaming.

overwrite : si True, le fichier de destination peut être écrasé (par défaut = False).

password (*) : Une chaîne sans espace pour protéger le document.

filtername (*) : Le nom d'un filtre qui doit être utilisé pour enregistrer le document. Si cet argument est passé, le filtre doit exister.

filteroptions (*) : une chaîne facultative d'options associées au filtre.

Exemple :

En Basic :

    oDoc.SaveAs("C:\Documents\NewCopy.odt", overwrite := True)
  
En Python

    doc.SaveAs(r"C:\Documents\NewCopy.odt", overwrite = True)
  

SaveCopyAs

Stocke une copie ou exporte le document vers l'emplacement de fichier donné. L'emplacement réel est inchangé.

Renvoie False si le document n'a pas pu être enregistré. Une erreur est générée lorsque le remplacement de la destination est rejeté ou lorsque la destination a son attribut en lecture seule défini.

Le document lui-même n'a pas besoin d'être actif pour exécuter cette méthode.

Syntaxe :

svc.SaveCopyAs(filename: str, overwrite: bool = False, password: str = '', filtername: str = '', filteroptions: str = ''): bool

Paramètres :

filename : une chaîne contenant le nom du fichier à utiliser. Il doit suivre la notation SF_FileSystem.FileNaming.

overwrite : si True, le fichier de destination peut être écrasé (par défaut = False).

password (*) : Une chaîne sans espace pour protéger le document.

filtername (*) : le nom d'un filtre qui doit être utilisé pour enregistrer le document. Si cet argument est passé, le filtre doit exister.

filteroptions (*) : une chaîne facultative d'options associées au filtre.

Exemple :

En Basic :

    oDoc.SaveCopyAs("C:\Documents\Copy2.odt", Overwrite := True)
  
En Python

    doc.SaveCopyAs(r"C:\Documents\Copy2.odt", overwrite = True)
  

SetPrinter

Définit les options d'impression du document.

Renvoie True en cas de succès.

Syntaxe :

svc.SetPrinter(opt printer: str, opt orientation: str, paperformat: str): bool

Paramètres :

printer : le nom de la file d'attente d'impression vers laquelle imprimer. En cas d'absence, l'imprimante par défaut est définie.

orientation : soit PORTRAIT ou PAYSAGE. Lorsque le paramètre est absent, reste inchangé par rapport aux paramètres de l'imprimante.

paperformat : spécifie le format du papier sous la forme d'une valeur de chaîne qui peut être soit A3, A4, A5, LETTER, LEGAL ou TABLOID. Reste inchangé en cas d'absence.

Exemple :

En Basic :

    oDoc.SetPrinter(Orientation := "PORTRAIT")
  
En Python

    doc.SetPrinter(paperformat='TABLOID')
  
warning

Toutes les routines ou identifiants de base ScriptForge qui sont préfixés par un caractère de soulignement "_" sont réservés à un usage interne. Ils ne sont pas destinés à être utilisés dans des macros de base ou des scripts Python.