SFDocuments.Document service/text/sbasic/shared/03/sf_document.xhpDocument service
SFDocuments.Document service
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 documentsAccessing standard or custom properties of documentsThe 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.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.
Service invocation
Before using the Document service the ScriptForge library needs to be loaded using:GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")The Document service is closely related to the UI and FileSystem services of the ScriptForge library.Below are three variants of how the Document service can be invoked.'1) From the ScriptForge.UI service:Dim ui As Object, oDoc As ObjectSet ui = CreateScriptService("UI")Set oDoc = ui.GetDocument("Untitled 1")'Alternatively, using the CreateDocument or OpenDocument methods' Set oDoc = ui.CreateDocument("Calc", ...)' Set oDoc = ui.OpenDocument("C:\MyFile.odt")'2) Directly if the document is already openDim oDoc As ObjectSet oDoc = CreateScriptService("SFDocuments.Document", "Untitled 1") 'Default = ActiveWindow'3) From a macro triggered by a document eventSub RunEvent(ByRef poEvent As Object) Dim oDoc As Object Set oDoc = CreateScriptService("SFDocuments.DocumentEvent", poEvent)The use of the prefix "SFDocuments." while calling the service is optional.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()API;DurationAPI;XComponentAPI;ODatabaseDocument
Properties
NameReadonlyTypeDescriptionCustomProperties (*)NoDictionary serviceReturns 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 (*)NoStringGives access to the Description property of the document (also known as "Comments")DocumentProperties (*)YesDictionary serviceReturns 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.DocumentTypeYesStringString value with the document type ("Base", "Calc", "Writer", etc)IsBase IsCalc IsDraw IsImpress IsMath IsWriterYesBooleanExactly one of these properties is True for a given document.Keywords (*)NoStringGives access to the Keywords property of the document. Represented as a comma-separated list of keywordsReadonly (*)YesBooleanTrue if the document is actually in read-only modeSubject (*)NoStringGives access to the Subject property of the document.Title (*)NoStringGives access to the Title property of the document.XComponentYesUNO ObjectThe UNO object com.sun.star.lang.XComponent or com.sun.star.comp.dba.ODatabaseDocument representing the document
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 ObjectSet oDoc = ui.OpenDocument("C:\Calc_Test.ods")Set oDoc = ui.OpenDocument("~/Documents/Calc_Test.ods")Set oDoc = ui.OpenDocument("C:\Calc_Test.ods")Dim propDict as ObjectSet propDict = oDoc.DocumentPropertiesDim keys as Variant : propKeys = propDict.KeysDim k as String, strProp as StringFor Each k In propKeys strProp = strProp & k & ": " & propDict.Item(k) & CHR$(10)Next kMsgBox strPropoDoc.CloseDocument()
List of Methods in the Document Service
Activate
CloseDocument
GetDatabase
RunCommand
Save
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.
oDoc.Activate() As Boolean
The example below considers that the file "My_File.ods" is already open but not active.Dim oDoc As ObjectSet oDoc = CreateScriptService("Document", "My_File.ods")oDoc.Activate()Keep in mind that you can invoke the Document service by passing to CreateScriptService either "Document" or "SFDocuments.Document" CloseDocument -------------------------------------------------------------------------------------------------------------------------- Document service;CloseDocument
CloseDocument
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.
oDoc.CloseDocument(SaveAsk As Boolean) As Boolean
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 ' ... GetDatabase -------------------------------------------------------------------------------------------------------------------------- Document service;GetDatabase
GetDatabase
This method is applicable only for Base documents.It returns a SFDatabases.Database service instance giving access to the execution of SQL commands on the database defined and/or embedded in the actual Base document.
oDoc.GetDatabase([User As String, [Password As String]])
User, Password : The login parameters. Both default to "".
Dim oDatabase As ObjectSet oDatabase = oDoc.GetDatabase("root", "pwd") RunCommand -------------------------------------------------------------------------------------------------------------------------- Document service;RunCommand
RunCommand
Runs a command on a document. The command is executed without arguments.A few typical commands are: Save, SaveAs, ExportToPDF, SetDocumentProperties, Undo, Copy, Paste, etc.The document itself does not need to be active to be able to run commands.
oDoc.RunCommand(Command As String)
Command : Case-sensitive string containing the command in English. The command itself is not checked for correctness. If nothing happens after the command call, then the command is probably wrong.
The following example runs the "SelectData" command in a Calc sheet named "My_File.ods", which will result in the selection of the data area based on the currently selected cell.Set oDoc = CreateScriptService("Document", "My_File.ods")oDoc.RunCommand("SelectData")The example above actually runs the UNO command uno:SelectData. Hence, to use the RunCommand method it is necessary to remove the "uno:" substring.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 -------------------------------------------------------------------------------------------------------------------------- Document service;Save
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.
oDoc.Save() As Boolean
If Not oDoc.Save() Then ' ... SaveAs -------------------------------------------------------------------------------------------------------------------------- Document service;SaveAs
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.
oDoc.SaveAs(FileName, [Overwrite As Boolean], [Password As String], [FilterName As String], [FilterOptions As String])
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.
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.
oDoc.SaveCopyAs(FileName, [Overwrite As Boolean], [Password As String], [FilterName As String], [FilterOptions As String])
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.