ScriptForge (FileSystem) Title arg for PickFolder()

Only Windows implements the Description
property of the FolderPicker by displaying
it in the dialog's header. Otherwise it
is ignored.

This commit harmonizes the behaviour
among all environments, including Linux.

The previous signature:
   fs.PickFolder(defaultdirectory, freetext)
is replaced by:
   fs.PickFolder(defaultdirectory, title, freetext)

The 'freetext' parameter is kept for backward
compatibility. It becomes obsolete. When present,
and 'title' is absent, its content is pushed
to the dialog's title.

The change is valid both for Basic and Python scripts.
The documentation should be updated accordingly.

Change-Id: I888ee4afa5046212081bbdedc849147ebda1a3bf
Reviewed-on: https://gerrit.libreoffice.org/c/core/+/184719
Reviewed-by: Jean-Pierre Ledure <jp@ledure.be>
Tested-by: Jenkins

wizards/source/scriptforge/SF_FileSystem.xba

@@ -1638,7 +1638,7 @@ Try:
 	End With
 
 	' Activate the filepicker dialog
-	Set oFileDialog = SF_Utils._GetUNOService("FilePicker")
+	Set oFileDialog = CreateUnoService("com.sun.star.ui.dialogs.FilePicker")	'	Do not reuse an existing FilePicker: TDF#154462
 	With oFileDialog
 		.Initialize(Array(iMode))
 
@@ -1683,13 +1683,16 @@ End Function    '   ScriptForge.SF_FileSystem.PickFile
 
 REM -----------------------------------------------------------------------------
 Public Function PickFolder(Optional ByVal DefaultFolder As Variant _
+							, Optional ByVal Title As Variant _
 							, Optional ByVal FreeText As Variant _
 							) As String
 '''	Display a FolderPicker dialog box
 '''	The method is not supported for document's internal file systems.
 '''	Args:
 '''		DefaultFolder: the FolderName from which to start. Default = the last selected folder
+'''		Title: text to display in the dialog header. Default is set by the desktop environment.
 '''		FreeText: text to display in the dialog. Default = ""
+'''			The argument is obsolete as from SF 25.8.
 '''	Returns:
 '''		The selected FolderName in URL or operating system format
 '''		The zero-length string if the dialog was cancelled
@@ -1704,27 +1707,34 @@ Dim iAccept As Integer			'	Value returned by the dialog (OK, Cancel, ..)
 Dim sFolder	As String			'	Return value					'	
 
 Const cstThisSub = "FileSystem.PickFolder"
-Const cstSubArgs = "[DefaultFolder=""""], [FreeText=""""]"
+Const cstSubArgs = "[DefaultFolder=""""], [Title=""""]"
 
 	If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
 	sFolder = ""
 
 Check:
 	If IsMissing(DefaultFolder) Or IsEmpty(DefaultFolder) Then DefaultFolder = ""
+	If IsMissing(Title) Or IsEmpty(Title) Then Title = ""
 	If IsMissing(FreeText) Or IsEmpty(FreeText) Then FreeText = ""
 	If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
 		If Not SF_Utils._ValidateFile(DefaultFolder, "DefaultFolder", , True) Then GoTo Finally
+		If Not SF_Utils._Validate(Title, "Title", V_STRING) Then GoTo Finally
 		If Not SF_Utils._Validate(FreeText, "FreeText", V_STRING) Then GoTo Finally
 	End If
 	If SF_FileSystem._IsDocFileSystem(DefaultFolder) Then GoTo CatchNotSupported
 	DefaultFolder = SF_FileSystem._ConvertToUrl(DefaultFolder)
 
+	'	Only Windows implements the Description property of the FolderPicker by displaying it in the title.
+	'	The method harmonizes the behaviour among all environments, including Linux.
+	If Len(FreeText) > 0 And Len(Title) = 0 Then Title = FreeText
+
 Try:
-	Set oFolderDialog = SF_Utils._GetUNOService("FolderPicker")
+	Set oFolderDialog = CreateUnoService("com.sun.star.ui.dialogs.FolderPicker")
 	If Not IsNull(oFolderDialog) Then
 		With oFolderDialog
 			If Len(DefaultFolder) > 0 Then .DisplayDirectory = ConvertToUrl(DefaultFolder)
-			.Description = FreeText
+			If Len(Title) > 0 Then .setTitle(Title)
+			If Len(FreeText) > 0 Then .setDescription(FreeText)
 			iAccept = .Execute()
 			' https://api.libreoffice.org/docs/idl/ref/ExecutableDialogResults_8idl.html
 			If iAccept = com.sun.star.ui.dialogs.ExecutableDialogResults.OK Then

wizards/source/scriptforge/SF_Root.xba

@@ -70,8 +70,6 @@ Private PrinterServer		As Object	' com.sun.star.awt.PrinterServer
 Private CharacterClass		As Object	' com.sun.star.i18n.CharacterClassification
 Private FileAccess			As Object	' com.sun.star.ucb.SimpleFileAccess
 Private FilterFactory		As Object	' com.sun.star.document.FilterFactory
-Private FolderPicker		As Object	' com.sun.star.ui.dialogs.FolderPicker
-Private FilePicker			As Object	' com.sun.star.ui.dialogs.FilePicker
 Private URLTransformer		As Object	' com.sun.star.util.URLTransformer
 Private Introspection		As Object	' com.sun.star.beans.Introspection
 Private BrowseNodeFactory	As Object	' com.sun.star.script.browse.BrowseNodeFactory
@@ -141,8 +139,6 @@ Private Sub Class_Initialize()
 	Set CharacterClass = Nothing
 	Set FileAccess = Nothing
 	Set FilterFactory = Nothing
-	Set FolderPicker = Nothing
-	Set FilePicker = Nothing
 	Set URLTransformer = Nothing
 	Set Introspection = Nothing
 	FileSystemNaming = "ANY"

wizards/source/scriptforge/SF_Utils.xba

@@ -378,19 +378,11 @@ Dim oDefaultContext As Object
 					Set .FileAccess = CreateUnoService("com.sun.star.ucb.SimpleFileAccess")
 				End If
 				Set _GetUNOService = .FileAccess
-			Case "FilePicker"
-				Set .FilePicker = CreateUnoService("com.sun.star.ui.dialogs.FilePicker")	'	Do not reuse an existing FilePicker: TDF#154462
-				Set _GetUNOService = .FilePicker
 			Case "FilterFactory"
 				If IsEmpty(.FilterFactory) Or IsNull(.FilterFactory) Then
 					Set .FilterFactory = CreateUnoService("com.sun.star.document.FilterFactory")
 				End If
 				Set _GetUNOService = .FilterFactory
-			Case "FolderPicker"
-				If IsEmpty(.FolderPicker) Or IsNull(.FolderPicker) Then
-					Set .FolderPicker = CreateUnoService("com.sun.star.ui.dialogs.FolderPicker")
-				End If
-				Set _GetUNOService = .FolderPicker
 			Case "FormatLocale"
 				If IsEmpty(.FormatLocale) Or IsNull(.FormatLocale) Then
 					.FormatLocale = CreateUnoStruct("com.sun.star.lang.Locale")

wizards/source/scriptforge/python/scriptforge.py

@@ -1270,8 +1270,10 @@ class SFScriptForge:
         def PickFile(self, defaultfile = ScriptForge.cstSymEmpty, mode = 'OPEN', filter = ''):
             return self.ExecMethod(self.vbMethod, 'PickFile', defaultfile, mode, filter)
 
-        def PickFolder(self, defaultfolder = ScriptForge.cstSymEmpty, freetext = ''):
-            return self.ExecMethod(self.vbMethod, 'PickFolder', defaultfolder, freetext)
+        def PickFolder(self, defaultfolder = ScriptForge.cstSymEmpty, title = '', freetext = ''):
+            if len(freetext) > 0 and len(title) == 0:
+                title = freetext
+            return self.ExecMethod(self.vbMethod, 'PickFolder', defaultfolder, title, freetext)
 
         def SubFolders(self, foldername, filter = '', includesubfolders = False):
             return self.ExecMethod(self.vbMethod + self.flgArrayRet, 'SubFolders', foldername,

wizards/source/scriptforge/python/scriptforge.pyi

@@ -1331,18 +1331,19 @@ class SFScriptForge:
                 """
             ...
 
-        def PickFolder(self, defaultfolder: FILE = ..., freetext: str = ...) -> FILE:
+        def PickFolder(self, defaultfolder: FILE = ..., title: str = ...) -> FILE:
             """
                 Display a dialog box to select a folder.
                     Args
                         ``defaultfolder``: the folder from which to start. Default = the last selected folder.
 
-                        ``freetext``: text to display in the dialog. Defaults to "".
+                        ``title``: an optional text to display in the dialog header.
                     Returns
                         The selected folder in ``filesystem.FileNaming`` notation.
                         A zero-length string if the dialog was cancelled.
                 """
             ...
+
         def SubFolders(self,
                        foldername: FILE,
                        filter: str = ...,

wizards/source/scriptforge/script.xlb

@@ -1,23 +1,23 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE library:library PUBLIC "-//OpenOffice.org//DTD OfficeDocument 1.0//EN" "library.dtd">
 <library:library xmlns:library="http://openoffice.org/2000/library" library:name="ScriptForge" library:readonly="false" library:passwordprotected="false">
- <library:element library:name="SF_Session"/>
- <library:element library:name="SF_Timer"/>
- <library:element library:name="SF_FileSystem"/>
- <library:element library:name="SF_Root"/>
- <library:element library:name="__License"/>
- <library:element library:name="SF_Utils"/>
- <library:element library:name="_ModuleModel"/>
- <library:element library:name="_CodingConventions"/>
- <library:element library:name="SF_Services"/>
- <library:element library:name="SF_UI"/>
- <library:element library:name="SF_Exception"/>
- <library:element library:name="SF_Dictionary"/>
  <library:element library:name="SF_TextStream"/>
  <library:element library:name="SF_Array"/>
  <library:element library:name="SF_Region"/>
  <library:element library:name="SF_L10N"/>
  <library:element library:name="SF_PythonHelper"/>
  <library:element library:name="SF_Platform"/>
+ <library:element library:name="SF_Utils"/>
+ <library:element library:name="SF_Root"/>
+ <library:element library:name="__License"/>
+ <library:element library:name="SF_Timer"/>
+ <library:element library:name="SF_FileSystem"/>
+ <library:element library:name="SF_Session"/>
+ <library:element library:name="SF_UI"/>
+ <library:element library:name="SF_Services"/>
+ <library:element library:name="SF_Dictionary"/>
+ <library:element library:name="SF_Exception"/>
+ <library:element library:name="_CodingConventions"/>
+ <library:element library:name="_ModuleModel"/>
  <library:element library:name="SF_String"/>
 </library:library>