From 7373f6259cd7270ab4263b54aa828c040fdaa133 Mon Sep 17 00:00:00 2001 From: Rafael Lima Date: Mon, 17 Jul 2023 14:39:17 +0200 Subject: Document new FileSystem feature in ScriptForge This patch also updates the documentation of the GetTempName method. Change-Id: Id15ddd909733a04ee5fe2ec208b9b010d0aa7de6 Reviewed-on: https://gerrit.libreoffice.org/c/help/+/154469 Tested-by: Jenkins Reviewed-by: Rafael Lima --- source/text/sbasic/shared/03/sf_document.xhp | 32 ++++++++++++ source/text/sbasic/shared/03/sf_filesystem.xhp | 71 ++++++++++++++++++++++++-- source/text/sbasic/shared/03/sf_toc.xhp | 5 +- 3 files changed, 102 insertions(+), 6 deletions(-) (limited to 'source') diff --git a/source/text/sbasic/shared/03/sf_document.xhp b/source/text/sbasic/shared/03/sf_document.xhp index 333f2e45cd..ea4b828aa5 100644 --- a/source/text/sbasic/shared/03/sf_document.xhp +++ b/source/text/sbasic/shared/03/sf_document.xhp @@ -111,6 +111,23 @@ API;Duration API;XComponent API;ODatabaseDocument + Document service;CustomProperties property + Document service;Description property + Document service;DocumentProperties property + Document service;DocumentType property + Document service;ExportFilters property + Document service;FileSystem property + Document service;ImportFilters property + Document service;IsBase property + Document service;IsCalc property + Document service;IsDraw property + Document service;IsImpress property + Document service;IsMath property + Document service;IsWriter property + Document service;Keywords property + Document service;Readonly property + Document service;Subject property + Document service;Title property

Properties

@@ -199,6 +216,21 @@ 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 + + + Yes + + + String + + + Returns a string with the URL path to the root of the virtual file system of the document. Use the FileSystem service to view its contents, as well as to create, open and read files stored in it. + Refer to this help page to learn more on how to access and manipulate folders and files in the virtual file system of a %PRODUCTNAME file. + + ImportFilters diff --git a/source/text/sbasic/shared/03/sf_filesystem.xhp b/source/text/sbasic/shared/03/sf_filesystem.xhp index 3dfb6a5e33..9c5e7cc50f 100644 --- a/source/text/sbasic/shared/03/sf_filesystem.xhp +++ b/source/text/sbasic/shared/03/sf_filesystem.xhp @@ -127,6 +127,66 @@ fs.BuildPath(...) +
+

Accessing the Virtual File System of a Document

+ %PRODUCTNAME document files are compressed ZIP files that contain the files and folders that represent the actual document contents. While the document is open, it is possible to access this virtual file system, explore its structure, as well as read and create files and folders. + The following example shows how to create a text file named myFile.txt and store it inside the document's virtual file system. +
+ + + GlobalScope.BasicLibraries.LoadLibrary("ScriptForge") + Dim oDoc As Object, fso As Object, oFile As Object + Dim sRoot, sFile, sMyDir + Set fso = CreateScriptService("FileSystem") + Set oDoc = CreateScriptService("Document", ThisComponent) + ' Gets the URL path notation to the root of the virtual file system + sRoot = oDoc.FileSystem() + sMyDir = sRoot & "myDir" + ' Creates the folder "myDir" if it does not exist + If Not fso.FolderExists(sMyDir) Then + fso.CreateFolder(sMyDir) + End If + ' Creates the file and write some text into it + sFile = fso.BuildPath(sMyDir, "myFile.txt") + oFile = fso.CreateTextFile(sFile) + oFile.WriteLine("Hello!") + oFile.CloseFile() + + + + from scriptforge import CreateScriptService + bas = CreateScriptService("Basic") + doc = CreateScriptService("Document", bas.ThisComponent) + fso = CreateScriptService("FileSystem") + sRoot = doc.FileSystem + sMyDir = sRoot + "myDir" + if not fso.FolderExists(sMyDir): + fso.CreateFolder(sMyDir) + sFile = fso.BuildPath(sMyDir, "myFile.txt") + oFile = fso.CreateTextFile(sFile) + oFile.WriteLine("Hello!") + oFile.CloseFile() + + In general, all methods of the FileSystem service can be used to manipulate files in the document's virtual file system. However, the following restrictions apply: + + + It is not possible to create files in the root folder. Use existing subfolders or create new folders to store files in the document's file system. + + + The FileNaming notation is always considered to be "URL". + + + The methods CompareFiles, GetFileModified, HashFile, PickFile and PickFolder are not applicable. + + + The method GetFileLen always returns zero. + + + The method Normalize always returns the input string unchanged. + + + The path to the virtual file system is not a physical address on the computer's hard drive. It can only be accessed from within a %PRODUCTNAME script and it only exists while the document file is open. + FileSystem service;FileNaming property FileSystem service;ConfigFolder property @@ -873,24 +933,27 @@

GetTempName

Returns a randomly generated temporary file name that is useful for performing operations that require a temporary file. - The returned file name does not have any suffix. The folder part of the returned string is the system's temporary folder. + By default, the returned file name does not have an extension. Use the extension parameter to specify the extension of the file name to be generated. + The folder part of the returned string is the system's temporary folder. The method does not create the temporary file. - svc.GetTempName(): str + svc.GetTempName(extension: str): str + + extension: The extension of the temporary file name (Default = ""). Dim fName As String FSO.FileNaming = "SYS" - fName = FSO.GetTempName() & ".txt" + fName = FSO.GetTempName(Extension := "txt") ' "/tmp/SF_574068.txt" fs.FileNaming = "SYS" - fName = FSO.GetTempName() + ".txt" + fName = FSO.GetTempName(extension = "txt") # "/tmp/SF_574068.txt"
diff --git a/source/text/sbasic/shared/03/sf_toc.xhp b/source/text/sbasic/shared/03/sf_toc.xhp index d74a25c9bb..a0ccfdcb3f 100644 --- a/source/text/sbasic/shared/03/sf_toc.xhp +++ b/source/text/sbasic/shared/03/sf_toc.xhp @@ -384,21 +384,22 @@ DocumentProperties
DocumentType
ExportFilters
- ImportFilters
+ FileSystem
+ ImportFilters
IsBase
IsCalc
IsDraw
IsImpress
IsMath
- IsWriter
 + IsWriter
Keywords
Readonly
Subject
-- cgit