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 :

command: Case-sensitive string containing the UNO command name. The inclusion of the prefix ".uno:" in the command is optional. The command itself is not checked for correctness. If nothing happens after the command call, then the command is probably wrong.

args: For each argument to be passed to the command, specify a pair containing the argument name and value.

Exemple :

En Basic :

The following example runs the SelectData command in a Calc file named "MyFile.ods", which will result in the selection of the data area based on the currently selected cell. Note that this command does not require any arguments.


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

Below is an example that runs the UNO command ReplaceAll and passes values for its arguments SearchString and ReplaceString. Running this command will replace all occurrence of the string "abc" by "ABC" in the current sheet.


    ' Arguments passed to the command:
    ' SearchString  = "abc"
    ' ReplaceString = "ABC"
    oDoc.RunCommand(".uno:ReplaceAll", "SearchString", "abc", "ReplaceString", "ABC")
  

Note that calling the command ReplaceAll without arguments will open the Find and Replace dialog.

En Python

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

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

In Python it is also possible to call RunCommand using keyword arguments:


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

Each LibreOffice component has its own set of commands available. One easy way to learn commands is going to Tools - Customize - Keyboard. When you position your mouse over a function in the Function list, a tooltip will appear with the corresponding UNO command.


Save

Stores the document to the file location from which it was loaded. The method is ignored if the document was not modified.

Returns False if the document could not be saved. An error is raised if the file is open as read-only, or if it is a new file that has not been saved yet.

The document itself does not need to be active to run this method.

Syntaxe :

svc.Save(): bool

Exemple :

En Basic :

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

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

SaveAs

Stores the document to the given file location. The new location becomes the new file name on which simple Save method calls will be applied.

Returns False if the document could not be saved. An error is raised when overwriting the destination is rejected or when the destination has its read-only attribute set.

The document itself does not need to be active to run this method.

Syntaxe :

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

Paramètres :

filename: A string containing the file name to be used. It must follow the SF_FileSystem.FileNaming notation.

overwrite: If True, the destination file may be overwritten (default = False).

password (*): A non-space string to protect the document.

filtername (*): The name of a filter that should be used for saving the document. If this argument is passed, then the filter must exist.

filteroptions (*): An optional string of options associated with the filter.

Exemple :

En Basic :

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

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

SaveCopyAs

Stores a copy of or export the document to the given file location. The actual location is unchanged.

Returns False if the document could not be saved. An error is raised when overwriting the destination is rejected or when the destination has its read-only attribute set.

The document itself does not need to be active to run this method.

Syntaxe :

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

Paramètres :

filename: A string containing the file name to be used. It must follow the SF_FileSystem.FileNaming notation.

overwrite: If True, the destination file may be overwritten (default = False).

password (*): A non-space string to protect the document.

filtername (*): The name of a filter that should be used for saving the document. If this argument is passed, then the filter must exist.

filteroptions (*): An optional string of options associated with the filter.

Exemple :

En Basic :

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

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

SetPrinter

Defines the printer options for the document.

Returns True when successful.

Syntaxe :

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

Paramètres :

printer: The name of the printer queue where to print to. When absent, the default printer is set.

orientation: Either PORTRAIT or LANDSCAPE. When absent, left unchanged with respect to the printer settings.

paperformat: Specifies the paper format as a string value that can be either A3, A4, A5, LETTER, LEGAL or TABLOID. Left unchanged when absent.

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.