LibreOffice 25.2 Súgó
The SFDocuments library provides methods and properties to facilitate the management and manipulation of LibreOffice documents.
Methods that are applicable for all types of documents (Text Documents, Sheets, Presentations, etc) are provided by the SFDocuments.Document service. Some examples are:
Opening, closing and saving documents
Accessing standard or custom properties of documents
The properties, methods or arguments marked with (*) are NOT applicable to Base documents.
Methods and properties that are specific to certain LibreOffice components are stored in separate services, such as SFDocuments.SF_Calc and SFDocuments.SF_Base.
Bár a Basic nyelv nem kínál öröklődést az objektumosztályok között, az utóbbi szolgáltatások a SFDocuments.Document szolgáltatás alosztályainak tekinthetők. Az ilyen alosztályok meghívhatják az alább ismertetett tulajdonságokat és metódusokat.
Before using the Document service the ScriptForge library needs to be loaded or imported:
Below are three variants of how the Document service can be invoked.
Using the getDocument method from the ScriptForge.UI service:
    Dim ui As Object, oDoc As Object
    Set ui = CreateScriptService("UI")
    Set oDoc = ui.GetDocument("Untitled 1")
  Alternatively you can use the methods CreateDocument and OpenDocument from the UI service.
    Set oDocA = ui.CreateDocument("Calc")
    Set oDocB = ui.OpenDocument("C:\Documents\MyFile.odt")
  Using a window name if the document is already open.
    Dim oDoc As Object
    Set oDoc = CreateScriptService("SFDocuments.Document", "Untitled 1") 'Default = ActiveWindow
  Using the document referenced by ThisComponent. This is specially useful when running a macro from within the Basic IDE.
    Dim oDoc As Object
    Set oDoc = CreateScriptService("Document", ThisComponent)
  From a macro triggered by a document event.
    Sub RunEvent(ByRef poEvent As Object)
        Dim oDoc As Object
        Set oDoc = CreateScriptService("SFDocuments.DocumentEvent", poEvent)
        ' (...)
    End Sub
  The Document service is closely related to the UI and FileSystem services.
Except when the document was closed by program with the CloseDocument method (it is then superfluous), it is recommended to free resources after use:
    Set oDoc = oDoc.Dispose()
  
    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")
  
    bas = CreateScriptService("Basic")
    doc = CreateScriptService("Document", bas.ThisComponent)
  
    def RunEvent(event)
        doc = CreateScriptService("SFDocuments.DocumentEvent", Event)
        # (...)
  The use of the prefix "SFDocuments." while calling the service is optional.
| Név | Írásvédett | Típus | Leírás | 
|---|---|---|---|
| CustomProperties (*) | Nem | Dictionary service | Visszaad egy ScriptForge.Dictionary objektumpéldányt. Frissítés után újra átadható a tulajdonságnak a dokumentum frissítéséhez. | 
| Description (*) | Nem | String | Gives access to the Description property of the document (also known as "Comments") | 
| DocumentProperties (*) | Igen | Dictionary service | Visszaad egy ScriptForge.Dictionary objektumot, amely tartalmazza az összes bejegyzést. A dokumentumstatisztikákat is tartalmazza. Vegye figyelembe, hogy ezek a dokumentum típusára jellemzőek. Egy Calc dokumentum például tartalmaz egy "CellCount" bejegyzést, amit más dokumentumok nem tartalmaznak. | 
| DocumentType | Igen | String | String value with the document type ("Base", "Calc", "Writer", etc) | 
| ExportFilters (*) | Igen | String array | Returns a list with the export filter names applicable to the current document as a zero-based array of strings. Filters used for both import/export are also returned. | 
| FileSystem | Igen | String | A dokumentum virtuális fájlrendszerének gyökeréhez vezető URL elérési útvonalát tartalmazó karakterláncot adja vissza. A FileSystem szolgáltatás segítségével megtekintheti annak tartalmát, valamint létrehozhatja, megnyithatja és olvashatja a benne tárolt fájlokat. Refer to this help page to learn more on how to access and manipulate folders and files in the virtual file system of a LibreOffice file. | 
| ImportFilters (*) | Igen | String array | Returns a list with the import filter names applicable to the current document as a zero-based array of strings. Filters used for both import/export are also returned. | 
| 
            IsBase | Igen | Boolean | Exactly one of these properties is True for a given document. | 
| Keywords (*) | Nem | String | Gives access to the Keywords property of the document. Represented as a comma-separated list of keywords | 
| Readonly (*) | Igen | Boolean | True if the document is actually in read-only mode | 
| StyleFamilies (*) | Igen | String array | List of available style families. Applicable to all document types except Base. | 
| Subject (*) | Nem | String | Gives access to the Subject property of the document. | 
| Title (*) | Nem | String | Gives access to the Title property of the document. | 
| XComponent | Igen | UNO objektum | The UNO object com.sun.star.lang.XComponent or com.sun.star.comp.dba.ODatabaseDocument representing the document. | 
| XDocumentSettings (*) | Igen | UNO objektum | A com.sun.star.XXX.DocumentSettings UNO object, where XXX is either sheet, text, drawing or presentation. This object gives access to the internal UNO properties that are specific to the document's type. | 
The example below prints all the properties of a document. Note that the oDoc object returned by the UI.OpenDocument method is a SFDocuments.Document object.
    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()
  To access document properties in a Python script the user needs to directly access them using their names, as shown below:
    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()
  | List of Methods in the Document Service | ||
|---|---|---|
| 
             Activate | ||
Returns True if the document could be activated. Otherwise, there is no change in the actual user interface. It is equivalent to the Activate method of the UI service.
This method is useful when one needs to give focus for a document that is minimized or hidden.
svc.Activate(): bool
The example below considers that the file "My_File.ods" is already open but not active.
    Dim oDoc As Object
    Set oDoc = CreateScriptService("Document", "MyFile.ods")
    oDoc.Activate()
  
    doc = CreateScriptService("Document", "MyFile.ods")
    doc.Activate()
  Keep in mind that you can invoke the Document service by passing to CreateScriptService either "Document" or "SFDocuments.Document"
Closes the document. If the document is already closed, regardless of how the document was closed, this method has no effect and returns False.
The method will also return False if the user declines to close it.
Returns True if the document was successfully closed.
svc.CloseDocument(saveask: bool = True): bool
saveask : If True (default), the user is invited to confirm if the changes should be written on disk. This argument is ignored if the document was not modified.
    If oDoc.CloseDocument(True) Then
        ' ...
    End If
  
    if doc.CloseDocument(True):
        # ...
  Creates a new menu entry in the menubar of a given document window.
This method returns an instance of the SFWidgets.Menu service.
A létrehozott menü csak az aktuális LibreOffice munkamenet alatt érhető el, és nem kerül mentésre sem a dokumentumban, sem a globális alkalmazásbeállításokban. Ezért a dokumentumablak bezárása a menü eltűnését eredményezi. Csak akkor jelenik meg újra, ha a menüt létrehozó makró ismét végrehajtásra kerül.
svc.CreateMenu(menuheader: str, [before: any], submenuchar: str = ">"): svc
menuheader: The toplevel name of the new menu.
before: Annak a meglévő menünek a neve (karakterláncként) vagy pozíciója (egész számként, 1-től kezdődően), amely elé az új menü kerül. Ha nincs érték megadva ennek az argumentumnak, a menü a menüsor utolsó pozíciójában jön létre.
submenuchar: The delimiter used to create menu trees when calling methods as AddItem from the Menu service. The default value is ">".
    Dim oDoc as Object, oMenu as Object
    Set oDoc = CreateScriptService("Document")
    Set oMenu = oDoc.CreateMenu("My Menu")
    With oMenu
        ' Add items to the menu
        .AddItem("Item A")
        .AddItem("Item B")
        ' ...
        ' After creating the menu, the service instance can be disposed of
        .Dispose()
    End With
  
    doc = CreateScriptService("Document")
    menu = doc.CreateMenu("My Menu")
    menu.AddItem("Item A")
    menu.AddItem("Item B")
    # ...
    menu.Dispose()
  Refer to the SFWidgets.Menu help page to learn more about how to create/remove menus in LibreOffice document windows.
Suppresses a single style or an array of styles given by their names within a specific styles family. Only user-defined styles may be deleted, built-in styles are ignored. It applies to all document types except Base and FormDocument.
svc.DeleteStyles(family: str, styleslist: str[1..*])
family: One of the style families present in the actual document, as a case-sensitive string. Valid family names can be retrieved using StyleFamilies property.
styleslist: A single style name as a string or an array of style names. The style names may be localized or not. The StylesList is typically the output of the execution of a Styles() method.
    ' Removing unused paragraph styles
    Const family = "ParagraphStyles"
    aList = oDoc.Styles(family, used := False, userDefined := True)
    oDoc.DeleteStyles(family, aList)
  
    # Removing styles according to a prefix
    a_list = doc.Styles('ParagraphStyles', namepattern = "Py*")
    doc.Styles('ParagraphStyles', a_list)
  Suspends user interface (UI) updates during the execution of a macro. Optionally, the mouse pointer can be changed into an hourglass while UI updates are suspended.
This method may provide some performance benefits for macros that perform numerous operations that require UI updates.
svc.Echo(echoon: bool = True, hourglass: bool = False)
echoon: Specify False to suspend UI updates. The default value is True, which enables real time UI updates.
hourglass: Specify True to change the mouse pointer to an hourglass (Default = False).
Moving the mouse pointer after it changed to an hourglass may cause it to switch to a different pointer depending on its new background.
    ' Suspends UI updates and change mouse pointer to an hourglass
    oDoc.Echo(EchoOn := False, HourGlass := True)
    ' Other macro commands
    ' ...
    ' Restores UI updates and mouse pointer
    oDoc.Echo()
  
    doc.Echo(echoon = False, hourglass = True)
    ...
    doc.Echo()
  Exports the document directly as a PDF file to the specified location. Returns True if the PDF file was successfully created.
The export options can be set either manually using the dialog or by calling the methods GetPDFExportOptions and SetPDFExportOptions from the Session service.
svc.ExportAsPDF(filename: str, overwrite: bool = False, opt pages: str, opt password: str, opt watermark: str): bool
filename: The full path and file name of the PDF to be created. It must follow the SF_FileSystem.FileNaming notation.
overwrite: Specifies if the destination file can be overwritten (Default = False). An error will occur if overwrite is set to False and the destination file already exists.
pages: String specifying which pages will be exported. This argument uses the same notation as in the dialog .
password: Specifies a password to open the PDF file.
watermark: Text to be used as watermark in the PDF file, which will be drawn in every page of the resulting PDF.
The following example exports the current document as a PDF file, defines a password and overwrites the destination file if it already exists.
    oDoc.ExportAsPDF("C:\User\Documents\myFile.pdf", Password := "1234", Overwrite := True)
  The code snippet below gets the current PDF export options and uses them to create the PDF file.
    Dim exportSettings as Object, oSession as Object
    oSession = CreateScriptService("Session")
    exportSettings = oSession.GetPDFExportOptions()
    ' Sets to True the option to export comments as PDF notes
    exportSettings.ReplaceItem("ExportNotes", True)
    oSession.SetPDFExportOptions(exportSettings)
    oDoc.ExportAsPDF("C:\User\Documents\myFile.pdf")
  
    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")
  This method sends the contents of the document to the default printer or to the printer defined by the SetPrinter method.
Returns True if the document was successfully printed.
svc.PrintOut(pages: str = "", copies: num = 1): bool
pages: The pages to print as a string, like in the user interface. Example: "1-4;10;15-18". Default is all pages.
copies: The number of copies. Default is 1.
    If oDoc.PrintOut("1-4;10;15-18", Copies := 2) Then
        ' ...
    End If
  
    if doc.PrintOut(copies=3, pages='45-88'):
        # ...
  Removes a toplevel menu from the menubar of a given document window.
Returns True if the specified menu could be removed. If the specified menu does not exist, the method returns False.
Ezzel a módszerrel bármely menübejegyzés eltávolítható a dokumentumablakból, beleértve az alapértelmezett menüket is. A menüsorban végrehajtott módosítások közül azonban egyik sem kerül mentésre a dokumentumba vagy az alkalmazás beállításaiba. A menüsor alapértelmezett beállításainak visszaállításához egyszerűen zárja be és nyissa meg újra a dokumentumablakot.
svc.RemoveMenu(menuheader: str): bool
menuheader: The toplevel name of the menu to be removed.
    Dim oDoc as Object
    Set oDoc = CreateScriptService("Document")
    oDoc.RemoveMenu("My Menu")
  
    doc = CreateScriptService("Document")
    doc.RemoveMenu("My Menu")
  Runs a UNO command on the document window associated with the service instance. A few typical commands are: Save, SaveAs, ExportToPDF, Undo, Copy, Paste, etc.
The document itself does not need to be active to be able to run commands.
Commands can be run with or without arguments. Arguments are not validated before running the command. If the command or its arguments are invalid, then nothing will happen.
For a complete list of UNO commands that can be run in LibreOffice, refer to the Wiki page Development/DispatchCommands.
svc.RunCommand(command: str, [args: any])
command: Nagy- és kisbetűket megkülönböztető karakterlánc, amely az UNO-parancs nevét tartalmazza. A ".uno:" előtag szerepeltetése a parancsban opcionális. Maga a parancs helyességét nem ellenőrzi a rendszer. Ha a parancshívás után nem történik semmi, akkor a parancs valószínűleg hibás.
args: For each argument to be passed to the command, specify a pair containing the argument name and value.
A következő példa a SelectData parancsot futtatja a "SajátFájl.ods" nevű Calc fájlban, ami az adatterület kiválasztását eredményezi az aktuálisan kiválasztott cella alapján. Vegye figyelembe, hogy ez a parancs nem igényel semmilyen argumentumot.
    Set oDoc = CreateScriptService("Document", "MyFile.ods")
    oDoc.RunCommand("SelectData")
  Az alábbi példában a ReplaceAll UNO-parancsot futtatja, és átadja a SearchString és ReplaceString argumentumok értékeit. A parancs futtatása az "abc" karakterlánc minden előfordulását "ABC"-vel helyettesíti az aktuális lapon.
    ' 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 dialog.
    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")
  Minden egyes LibreOffice komponensnek saját parancskészlete áll rendelkezésre. A parancsok megismerésének egyik egyszerű módja az Eszközök - Testreszabás - Billentyűzet menüpontban található. Ha az egeret a Funkció listában egy funkció fölé helyezi, megjelenik egy helyi súgó a megfelelő UNO-paranccsal.
Stores the document to the file location from which it was loaded. The method is ignored if the document was not modified.
False értéket ad vissza, ha a dokumentumot nem sikerült elmenteni. Hibaüzenet érkezik, ha a fájl írásvédettként van megnyitva, vagy ha új fájlról van szó, amelyet még nem mentett el.
The document itself does not need to be active to run this method.
svc.Save(): bool
    If Not oDoc.Save() Then
        ' ...
    End If
  
    if not doc.Save():
        # ...
  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.
svc.SaveAs(filename: str, overwrite: bool = False, password: str = '', filtername: str = '', filteroptions: str = ''): bool
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.
    oDoc.SaveAs("C:\Documents\NewCopy.odt", overwrite := True)
  
    doc.SaveAs(r"C:\Documents\NewCopy.odt", overwrite = True)
  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.
svc.SaveCopyAs(filename: str, overwrite: bool = False, password: str = '', filtername: str = '', filteroptions: str = ''): bool
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.
    oDoc.SaveCopyAs("C:\Documents\Copy2.odt", Overwrite := True)
  
    doc.SaveCopyAs(r"C:\Documents\Copy2.odt", overwrite = True)
  Defines the printer options for the document.
Returns True when successful.
svc.SetPrinter(opt printer: str, opt orientation: str, paperformat: str): bool
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.
    oDoc.SetPrinter(Orientation := "PORTRAIT")
  
    doc.SetPrinter(paperformat='TABLOID')
  Retrieves a list of styles matching an optional compound criteria, the returned array may be empty. It applies to all document types except Base.
svc.Styles(family, opt namepattern: str, opt used: bool, opt userdefined: bool, opt parentstyle: str, opt category: str): str[0..*])
category: A case-insensitive string: TEXT, CHAPTER, LIST, INDEX, EXTRA, HTML. For their respective meanings, refer to paragraph style category API documentation.
This argument is ignored when the Family differs from "ParagraphStyles".
namepattern: A filter on the style names, as a case-sensitive string pattern. The names include the internal and localized names.
Admitted wildcard are:
the "?" representing any single character.
the "*" representing zero, one, or multiple characters
parentstyle: When present, only the children of the given, localized or not, parent style name are retained.
used: When True, the style must be used in the document, when absent the argument is ignored.
userdefined: When True, the style must have been added by the user, either in the document or its template, when absent, the argument is ignored.
    Dim vStyles As Variant
    vStyles = oDoc.Styles("ParagraphStyles") 'All styles in the family
    vStyles = oDoc.Styles("ParagraphStyles", "H*") 'Heading, Heading 1, ...
    vStyles = oDoc.Styles("ParagraphStyles", Used := False, UserDefined := True) ' All user-defined styles that are not used
    vStyles = oDoc.Styles("ParagraphStyles", ParentStyle := "Standard") ' All styles derived from the 'Default Paragraph Style'
  
    vStyles = doc.Styles('ParagraphStyles')  #All styles in the family
    vStyles = doc.Styles('ParagraphStyles', 'H*')  #Heading, Heading 1, ...
    vStyles = doc.Styles('ParagraphStyles', Used = False, UserDefined = True)  # All user-defined styles that are not used
    vStyles = doc.Styles('ParagraphStyles', ParentStyle = 'Standard")  # All styles derived from the "Default Paragraph Style"
  This method returns either a list of the available toolbar names in the actual document or an instance SFWidgets.Toolbar service.
    svc.Toolbars(opt ToolbarName: str): uno
    svc.Toolbars(): str[0..]
  
ToolbarName: The usual name of one of the available toolbars.
    Dim oToolbar As Object
    Set oToolbar = oDoc.Toolbars("myToolbar")
  
    a_list = doc.Toolbars()
  This method returns the UNO representation of a given style for all document types except Base. Nothing is returned when the StyleName does not exist in the given family.
svc.XStyles(family: str, stylename: str): uno
stylename: One of the styles present in the given family, as a case-sensitive string. The StyleName may be localized or not.
    Dim oStyle As Object
    Set oStyle = oDoc.XStyle("ParagraphStyle", "Heading 2")
  
    oStyle = doc.XStyle('ParagraphStyle', 'Heading 2')