KmD7j‖SFDocuments.Document service

FoEeH‖The SFDocuments library provides methods and properties to facilitate the management and manipulation of LibreOffice documents.

urZhL‖Methods that are applicable for all types of documents (Text Documents, Sheets, Presentations, etc) are provided by the SFDocuments.Document service. Some examples are:

warning

C6JgF‖The properties, methods or arguments marked with (*) are NOT applicable to Base documents.


HPr8i‖Methods and properties that are specific to certain LibreOffice components are stored in separate services, such as SFDocuments.SF_Calc and SFDocuments.SF_Base.

Fdi8i‖Although the Basic language does not offer inheritance between object classes, the latter services may be considered as subclasses of the SFDocuments.Document service. Such subclasses can invoke the properties and methods described below.

YMWaA‖Service invocation

XVADJ‖Before using the Document service the ScriptForge library needs to be loaded or imported:

note

gF8D8‖• Basic macros require to load ScriptForge library using the following statement:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Python scripts require an import from scriptforge module:
from scriptforge import CreateScriptService


X6BV3‖Below are three variants of how the Document service can be invoked.

3aa4B‖In Basic

o39cT‖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")
  

6AZF9‖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")
  

kv6B9‖Directly if the document is already open.


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

yFDEW‖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
  
note

FxfW2‖The Document service is closely related to the UI and FileSystem services.


QF9FG‖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()
  
BenDd‖In 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

LyvNw‖The use of the prefix "SFDocuments." while calling the service is optional.


z3oxC‖Properties

6NTY6‖Name

wUbi9‖Readonly

NfJEr‖Type

QZzvi‖Description

CustomProperties (*)

wBpru‖No

Dictionary service

QEZC4‖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 (*)

DktDb‖No

String

DNFGz‖Gives access to the Description property of the document (also known as "Comments")

DocumentProperties (*)

wMzx8‖Yes

Dictionary service

Mm6E5‖Returns a ScriptForge.Dictionary object containing all the entries. Document statistics are included. Note that they are specific to the type of document. As an example, a Calc document includes a "CellCount" entry. Other documents do not.

DocumentType

Ew7vi‖Yes

String

Aw2Tv‖String value with the document type ("Base", "Calc", "Writer", etc)

IsBase
IsCalc
IsDraw
IsImpress
IsMath
IsWriter

Yo8T4‖Yes

Boolean

pSbRu‖Exactly one of these properties is True for a given document.

Keywords (*)

oKQWB‖No

String

CDTBC‖Gives access to the Keywords property of the document. Represented as a comma-separated list of keywords

Readonly (*)

EHM84‖Yes

Boolean

JGTQz‖True if the document is actually in read-only mode

Subject (*)

zK55N‖No

String

99ZxC‖Gives access to the Subject property of the document.

Title (*)

dH6ct‖No

String

TCiBh‖Gives access to the Title property of the document.

XComponent

SwDBh‖Yes

PRmJE‖UNO Object

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


EFSA4‖Example:

3aa4B‖In Basic

coFyk‖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()
  
BenDd‖In Python

eqL5J‖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()
  

wmiy9‖List of Methods in the Document Service

Activate
CloseDocument
CreateMenu
ExportAsPDF

PrintOut
RemoveMenu
RunCommand
Save

SaveAs
SaveCopyAs
SetPrinter


Activate

UVWQb‖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.

qcuXA‖This method is useful when one needs to give focus for a document that is minimized or hidden.

FVEx2‖Syntax:

svc.Activate(): bool

EFSA4‖Example:

vFzrg‖The example below considers that the file "My_File.ods" is already open but not active.

3aa4B‖In Basic

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

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

zGRcs‖Keep in mind that you can invoke the Document service by passing to CreateScriptService either "Document" or "SFDocuments.Document"


CloseDocument

rB7Ab‖Closes the document. If the document is already closed, regardless of how the document was closed, this method has no effect and returns False.

64F7E‖The method will also return False if the user declines to close it.

AGBjg‖Returns True if the document was successfully closed.

FVEx2‖Syntax:

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

WADQ4‖Parameters:

Wt7L9‖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.

EFSA4‖Example:

3aa4B‖In Basic

    If oDoc.CloseDocument(True) Then
        ' ...
    End If
  
BenDd‖In Python

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

CreateMenu

RhAbC‖Creates a new menu entry in the menubar of a given document window.

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

note

GKeq5‖The menu created is only available during the current LibreOfficeDev session and is not saved neither in the document nor in the global application settings. Hence closing the document window will make the menu disappear. It will only reappear when the macro that creates the menu is executed again.


FVEx2‖Syntax:

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

WADQ4‖Parameters:

szVYB‖menuheader: The toplevel name of the new menu.

iCSZE‖before: The name (as a string) or position (as an integer starting at 1) of an existing menu before which the new menu will be placed. If no value is defined for this argument, the menu will be created at the last position in the menubar.

LX4b9‖submenuchar: The delimiter used to create menu trees when calling methods as AddItem from the Menu service. The default value is ">".

EFSA4‖Example:

3aa4B‖In Basic

    Dim oDoc as Object, oMenu as Object
    Set oDoc = CreateScriptService("Document")
    FhwFZ‖Set oMenu = oDoc.CreateMenu("My Menu")
    With oMenu
    h3wAE‖    ' Add items to the menu
        .AddItem("Item A")
        .AddItem("Item B")
        ' ...
    ZpygS‖    ' After creating the menu, the service instance can be disposed of
        .Dispose()
    End With
  
BenDd‖In Python

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

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


ExportAsPDF

CGKZA‖Exports the document directly as a PDF file to the specified location. Returns True if the PDF file was successfully created.

PBk4E‖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.

FVEx2‖Syntax:

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

WADQ4‖Parameters:

SFwEd‖filename: The full path and file name of the PDF to be created. It must follow the SF_FileSystem.FileNaming notation.

E6KyY‖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.

d9RRn‖pages: String specifying which pages will be exported. This argument uses the same notation as in the dialog File - Export As - Export as PDF.

kBDPk‖password: Specifies a password to open the PDF file.

joeXi‖watermark: Text to be used as watermark in the PDF file, which will be drawn in every page of the resulting PDF.

EFSA4‖Example:

3aa4B‖In Basic

NmChF‖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)
  

wEW7B‖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()
    7uUWr‖' 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")
  
BenDd‖In 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

HNC9m‖This method sends the contents of the document to the default printer or to the printer defined by the SetPrinter method.

CJxTR‖Returns True if the document was successfully printed.

FVEx2‖Syntax:

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

WADQ4‖Parameters:

uQMeV‖pages: The pages to print as a string, like in the user interface. Example: "1-4;10;15-18". Default is all pages.

EHtFi‖copies: The number of copies. Default is 1.

EFSA4‖Example:

3aa4B‖In Basic

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

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

RemoveMenu

VDMiZ‖Removes a toplevel menu from the menubar of a given document window.

wfDbr‖Returns True if the specified menu could be removed. If the specified menu does not exist, the method returns False.

note

eNVDJ‖This method can be used to remove any menu entry from the document window, including default menus. However, none of these changes in the menubar are saved to the document or to the application settings. To restore the menubar to the default settings, simply close and reopen the document window.


FVEx2‖Syntax:

svc.RemoveMenu(menuheader: str): bool

WADQ4‖Parameters:

E6ahL‖menuheader: The toplevel name of the menu to be removed.

EFSA4‖Example:

3aa4B‖In Basic

    Dim oDoc as Object
    Set oDoc = CreateScriptService("Document")
    yRoDW‖oDoc.RemoveMenu("My Menu")
  
BenDd‖In Python

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

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


RunCommand

Ab7PE‖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.

qBhYc‖The document itself does not need to be active to be able to run commands.

9FuBU‖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.

tip

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


FVEx2‖Syntax:

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

WADQ4‖Parameters:

HBVsV‖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.

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

EFSA4‖Example:

3aa4B‖In Basic

MqEx7‖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")
  

GGDgF‖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.


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

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

BenDd‖In Python

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

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

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


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

m9AyA‖Each LibreOfficeDev 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

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

sFUcr‖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.

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

FVEx2‖Syntax:

svc.Save(): bool

EFSA4‖Example:

3aa4B‖In Basic

    If Not oDoc.Save() Then
        ' ...
    End If
  
BenDd‖In Python

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

SaveAs

75K92‖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.

R8D2A‖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.

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

FVEx2‖Syntax:

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

WADQ4‖Parameters:

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

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

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

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

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

EFSA4‖Example:

3aa4B‖In Basic

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

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

SaveCopyAs

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

ovvew‖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.

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

FVEx2‖Syntax:

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

WADQ4‖Parameters:

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

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

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

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

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

EFSA4‖Example:

3aa4B‖In Basic

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

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

SetPrinter

96EBt‖Defines the printer options for the document.

zoaQX‖Returns True when successful.

FVEx2‖Syntax:

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

WADQ4‖Parameters:

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

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

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

EFSA4‖Example:

3aa4B‖In Basic

    oDoc.SetPrinter(Orientation := "PORTRAIT")
  
BenDd‖In Python

    doc.SetPrinter(paperformat='TABLOID')
  
warning

uzETY‖All ScriptForge Basic routines or identifiers that are prefixed with an underscore character "_" are reserved for internal use. They are not meant be used in Basic macros or Python scripts.