ScriptForge - (SF_Document) new SetPrinter() method

The SetPrinter() method is applicable to any document type,
except Base documents.
It is also applicable to Base form documents with an
additional "FormDocument" argument.

Implemented in Basic and in Python.

The method defines next printer settings:
- the printer name
- the orientation
- the paper format

The settings are kept per document or form document

To bypass array management troubles in Basic,
the SF_Utils._SetPropertyValue() Sub is converted to a Function.
(no user scripts impact, only internal use).

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

7 files changed, 203 insertions, 23 deletions

diff --git a/wizards/source/scriptforge/SF_Array.xba b/wizards/source/scriptforge/SF_Array.xba
index 9930574b6b10..49bdab14770a 100644
--- a/wizards/source/scriptforge/SF_Array.xba
+++ b/wizards/source/scriptforge/SF_Array.xba
@@ -1008,8 +1008,8 @@ Public Function IndexOf(Optional ByRef Array_1D As Variant _
 '''		SF_Array.IndexOf(Array("A","B","c","D"), "C", SortOrder := "ASC") returns 2
 '''		SF_Array.IndexOf(Array("A","B","c","D"), "C", CaseSensitive := True) returns -1
 
-Dim vFindItem() As Variant			'	2-items array (0) = True if found, (1) = Index where found
-Dim lIndex As Long				'	Return value
+Dim vFindItem As Variant			'	2-items array (0) = True if found, (1) = Index where found
+Dim lIndex As Long					'	Return value
 Dim iToFindType As Integer			'	VarType of ToFind
 Const cstThisSub = "Array.IndexOf"
 Const cstSubArgs = "Array_1D, ToFind, [CaseSensitive=False], [SortOrder=""""|""ASC""|""DESC""]"
diff --git a/wizards/source/scriptforge/SF_Utils.xba b/wizards/source/scriptforge/SF_Utils.xba
index be2a9fd91cc7..2f2044cafcc8 100644
--- a/wizards/source/scriptforge/SF_Utils.xba
+++ b/wizards/source/scriptforge/SF_Utils.xba
@@ -586,35 +586,40 @@ Const cstContinue = "…"			'	Unicode continuation char U+2026
 End Function	'	ScriptForge.SF_Utils._ReprValues
 
 REM -----------------------------------------------------------------------------
-Public Sub _SetPropertyValue(ByRef pvPropertyValue As Variant _
+Public Function _SetPropertyValue(ByVal pvPropertyValue As Variant _
 									, ByVal psName As String _
 									, ByRef pvValue As Variant _
-									)
-'''	Update the 1st argument (passed by reference), which is an array of property values
-'''	If the property psName exists, update it with pvValue, otherwise create it on top of the array
+									) As variant
+'''	Return the 1st argument (passed by reference), which is an array of property values
+'''	If the property psName exists, update it with pvValue, otherwise create it on top of the returned array
 
 Dim oPropertyValue As New com.sun.star.beans.PropertyValue
 Dim lIndex As Long				'	Found entry
 Dim vValue As Variant			'	Alias of pvValue
+Dim vProperties As Variant		'	Alias of pvPropertyValue
 Dim i As Long
 
 	lIndex = -1
-	For i = 0 To UBound(pvPropertyValue)
-		If pvPropertyValue(i).Name = psName Then
+	vProperties = pvPropertyValue
+	For i = 0 To UBound(vProperties)
+		If vProperties(i).Name = psName Then
 			lIndex = i
 			Exit For
 		End If
 	Next i
 	If lIndex < 0 Then		'	Not found
-		lIndex = UBound(pvPropertyValue) + 1
-		ReDim Preserve pvPropertyValue(0 To lIndex)
+		lIndex = UBound(vProperties) + 1
+		ReDim Preserve vProperties(0 To lIndex)
 		Set oPropertyValue = SF_Utils._MakePropertyValue(psName, pvValue)
-		pvPropertyValue(lIndex) = oPropertyValue
+		vProperties(lIndex) = oPropertyValue
+		vProperties = vProperties
 	Else					'	psName exists already in array of property values
-		pvPropertyValue(lIndex).Value = SF_Utils._CPropertyValue(pvValue)
+		vProperties(lIndex).Value = SF_Utils._CPropertyValue(pvValue)
 	End If
+
+	_SetPropertyValue = vProperties
 	
-End Sub			'	ScriptForge.SF_Utils._SetPropertyValue
+End Function	'	ScriptForge.SF_Utils._SetPropertyValue
 
 REM -----------------------------------------------------------------------------
 Private Function _TypeNames(Optional ByVal pvArgs As Variant) As String
diff --git a/wizards/source/scriptforge/python/scriptforge.py b/wizards/source/scriptforge/python/scriptforge.py
index 55584406bef3..1d7bd96fa2c5 100644
--- a/wizards/source/scriptforge/python/scriptforge.py
+++ b/wizards/source/scriptforge/python/scriptforge.py
@@ -1761,6 +1761,9 @@ class SFDocuments:
             return self.ExecMethod(self.vbMethod, 'SaveCopyAs', filename, overwrite,
                                    password, filtername, filteroptions)
 
+        def SetPrinter(self, printer = '', orientation = '', paperformat = ''):
+            return self.ExecMethod(self.vbMethod, 'SetPrinter', printer, orientation, paperformat)
+
     # #########################################################################
     # SF_Base CLASS
     # #########################################################################
@@ -1803,6 +1806,9 @@ class SFDocuments:
         def OpenFormDocument(self, formdocument, designmode = False):
             return self.ExecMethod(self.vbMethod, 'OpenFormDocument', formdocument, designmode)
 
+        def SetPrinter(self, formdocument = '', printer = '', orientation = '', paperformat = ''):
+            return self.ExecMethod(self.vbMethod, 'SetPrinter', formdocument, printer, orientation, paperformat)
+
     # #########################################################################
     # SF_Calc CLASS
     # #########################################################################
@@ -2092,7 +2098,7 @@ class SFDocuments:
             """
                 Transform positional and keyword arguments into positional only
                 """
-            return (windowname,)
+            return windowname,
 
         def Forms(self, form = ''):
             return self.ExecMethod(self.vbMethod + self.flgArrayRet, 'Forms', form)
diff --git a/wizards/source/sfdocuments/SF_Base.xba b/wizards/source/sfdocuments/SF_Base.xba
index 87d95152a24e..7ed8360c4fd0 100644
--- a/wizards/source/sfdocuments/SF_Base.xba
+++ b/wizards/source/sfdocuments/SF_Base.xba
@@ -194,7 +194,7 @@ Public Function Forms(Optional ByVal FormDocument As Variant _
 '''				Set myForm = oDoc.Forms("Folder1/myFormDocument", 0)
 
 Dim oForm As Object					'	The new Form class instance
-Dim oFormDocument As Object				'	com.sun.star.comp.sdb.Content
+Dim oFormDocument As Object			'	com.sun.star.comp.sdb.Content
 Dim oXForm As Object				'	com.sun.star.form.XForm
 Dim vFormDocuments As Variant		'	Array of form documents
 Dim vFormNames As Variant			'	Array of form names
@@ -487,6 +487,67 @@ Public Function Properties() As Variant
 End Function	'	SFDocuments.SF_Base.Properties
 
 REM -----------------------------------------------------------------------------
+Public Function SetPrinter(Optional ByVal FormDocument As Variant _
+							, Optional ByVal Printer As Variant _
+							, Optional ByVal Orientation As Variant _
+							, Optional ByVal PaperFormat As Variant _
+							) As Boolean
+''' Define the printer options for a form document. The form document must be open.
+'''	Args:
+'''		FormDocument: a valid document form name as a case-sensitive string
+'''		Printer: the name of the printer queue where to print to
+'''			When absent or space, the default printer is set
+'''		Orientation: either "PORTRAIT" or "LANDSCAPE". Left unchanged when absent
+'''		PaperFormat: one of next values
+'''			"A3", "A4", "A5", "B4", "B5", "LETTER", "LEGAL", "TABLOID"
+'''			Left unchanged when absent
+'''		_PrintComponent: undocumented argument to determine the component
+'''			Useful typically to apply printer settings on a Base form document
+'''	Returns:
+'''		True when successful
+'''	Examples:
+'''		oDoc.SetPrinter("myForm", Orientation := "PORTRAIT")
+
+Dim bPrinter As Boolean				'	Return value
+Dim vFormDocuments As Variant		'	Array of form documents
+Dim oFormDocument As Object			'	com.sun.star.comp.sdb.Content
+
+Const cstThisSub = "SFDocuments.Base.SetPrinter"
+Const cstSubArgs = "FormDocument, [Printer=""""], [Orientation=""PORTRAIT""|""LANDSCAPE""]" _
+						& ", [PaperFormat=""A3""|""A4""|""A5""|""B4""|""B5""|""LETTER""|""LEGAL""|""TABLOID"""
+
+	If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
+	bPrinter = False
+
+Check:
+	If IsMissing(Printer) Or IsEmpty(Printer) Then Printer = ""
+	If IsMissing(Orientation) Or IsEmpty(Orientation) Then Orientation = ""
+	If IsMissing(PaperFormat) Or IsEmpty(PaperFormat) Then PaperFormat = ""
+	
+	If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
+		If Not _IsStillAlive() Then GoTo Finally
+		'	Build list of available FormDocuments recursively with _CollectFormDocuments
+		If IsNull(_FormDocuments) Then Set _FormDocuments = _Component.getFormDocuments()
+		vFormDocuments = Split(_CollectFormDocuments(_FormDocuments), cstToken)
+		If Not ScriptForge.SF_Utils._Validate(FormDocument, "FormDocument", V_STRING, vFormDocuments) Then GoTo Finally
+	End If
+	If Not IsLoaded(FormDocument) Then GoTo CatchClosed
+
+Try:
+	Set oFormDocument = _FormDocuments.getByHierarchicalName(FormDocument)
+	bPrinter = [_Super].SetPrinter(Printer, Orientation, PaperFormat, oFormDocument.Component)
+
+Finally:
+	SetPrinter = bPrinter
+	ScriptForge.SF_Utils._ExitFunction(cstThisSub)
+	Exit Function
+Catch:
+	GoTo Finally
+CatchClosed:
+	ScriptForge.SF_Exception.RaiseFatal(FORMDEADERROR, FormDocument, _FileIdent())
+End Function   '   SFDocuments.SF_Base.SetPrinter
+
+REM -----------------------------------------------------------------------------
 Public Function SetProperty(Optional ByVal PropertyName As Variant _
 								, Optional ByRef Value As Variant _
 								) As Boolean
diff --git a/wizards/source/sfdocuments/SF_Calc.xba b/wizards/source/sfdocuments/SF_Calc.xba
index 75717c57d572..f5247088d2a2 100644
--- a/wizards/source/sfdocuments/SF_Calc.xba
+++ b/wizards/source/sfdocuments/SF_Calc.xba
@@ -2026,11 +2026,11 @@ Try:
 	'	Initialize the sort descriptor
 	Set oRange = oRangeAddress.XCellRange
 	vSortDescriptor = oRange.createSortDescriptor
-	ScriptForge.SF_Utils._SetPropertyValue(vSortDescriptor, "IsSortColumns", SortColumns)
-	ScriptForge.SF_Utils._SetPropertyValue(vSortDescriptor, "ContainsHeader", ContainsHeader)
-	ScriptForge.SF_Utils._SetPropertyValue(vSortDescriptor, "BindFormatsToContent", True)
+	vSortDescriptor = ScriptForge.SF_Utils._SetPropertyValue(vSortDescriptor, "IsSortColumns", SortColumns)
+	vSortDescriptor = ScriptForge.SF_Utils._SetPropertyValue(vSortDescriptor, "ContainsHeader", ContainsHeader)
+	vSortDescriptor = ScriptForge.SF_Utils._SetPropertyValue(vSortDescriptor, "BindFormatsToContent", True)
 	If Len(DestinationCell) = 0 Then
-		ScriptForge.SF_Utils._SetPropertyValue(vSortDescriptor, "CopyOutputData", False)
+		vSortDescriptor = ScriptForge.SF_Utils._SetPropertyValue(vSortDescriptor, "CopyOutputData", False)
 	Else
 		Set oDestAddress = oDestRange.XCellRange.RangeAddress
 		Set oDestCell = New com.sun.star.table.CellAddress
@@ -2039,10 +2039,10 @@ Try:
 			oDestCell.Column = .StartColumn
 			oDestCell.Row = .StartRow
 		End With
-		ScriptForge.SF_Utils._SetPropertyValue(vSortDescriptor, "CopyOutputData", true)
-		ScriptForge.SF_Utils._SetPropertyValue(vSortDescriptor, "OutputPosition", oDestCell)
+		vSortDescriptor = ScriptForge.SF_Utils._SetPropertyValue(vSortDescriptor, "CopyOutputData", True)
+		vSortDescriptor = ScriptForge.SF_Utils._SetPropertyValue(vSortDescriptor, "OutputPosition", oDestCell)
 	End If
-	ScriptForge.SF_Utils._SetPropertyValue(vSortDescriptor, "IsUserListEnabled", False)
+	vSortDescriptor = ScriptForge.SF_Utils._SetPropertyValue(vSortDescriptor, "IsUserListEnabled", False)
 
 	'	Define the sorting keys
 	vSortFields = Array()
@@ -2059,7 +2059,7 @@ Try:
 	Next i
 
 	'	Associate the keys and the descriptor, and sort
-	ScriptForge.SF_Utils._SetPropertyValue(vSortDescriptor, "SortFields", vSortFields)
+	vSortDescriptor = ScriptForge.SF_Utils._SetPropertyValue(vSortDescriptor, "SortFields", vSortFields)
 	oRange.sort(vSortDescriptor)
 
 	'	Compute the changed area
@@ -2223,6 +2223,14 @@ Public Function SaveCopyAs(Optional ByVal FileName As Variant _
 	SaveCopyAs = [_Super].SaveCopyAs(FileName, Overwrite, Password, FilterName, FilterOptions)
 End Function   '   SFDocuments.SF_Calc.SaveCopyAs
 
+REM -----------------------------------------------------------------------------
+Public Function SetPrinter(Optional ByVal Printer As Variant _
+							, Optional ByVal Orientation As Variant _
+							, Optional ByVal PaperFormat As Variant _
+							) As Boolean
+	SetPrinter = [_Super].SetPrinter(Printer, Orientation, PaperFormat)
+End Function	'   SFDocuments.SF_Calc.SetPrinter
+
 REM =========================================================== PRIVATE FUNCTIONS
 
 REM -----------------------------------------------------------------------------
diff --git a/wizards/source/sfdocuments/SF_Document.xba b/wizards/source/sfdocuments/SF_Document.xba
index 849b357e643e..85eafb39dd84 100644
--- a/wizards/source/sfdocuments/SF_Document.xba
+++ b/wizards/source/sfdocuments/SF_Document.xba
@@ -808,6 +808,98 @@ CatchError:
 End Function   '   SFDocuments.SF_Document.SaveCopyAs
 
 REM -----------------------------------------------------------------------------
+Public Function SetPrinter(Optional ByVal Printer As Variant _
+							, Optional ByVal Orientation As Variant _
+							, Optional ByVal PaperFormat As Variant _
+							, Optional ByRef _PrintComponent As Variant _
+							) As Boolean
+''' Define the printer options for the document
+'''	Args:
+'''		Printer: the name of the printer queue where to print to
+'''			When absent or space, the default printer is set
+'''		Orientation: either "PORTRAIT" or "LANDSCAPE". Left unchanged when absent
+'''		PaperFormat: one of next values
+'''			"A3", "A4", "A5", "B4", "B5", "LETTER", "LEGAL", "TABLOID"
+'''			Left unchanged when absent
+'''		_PrintComponent: undocumented argument to determine the component
+'''			Useful typically to apply printer settings on a Base form document
+'''	Returns:
+'''		True when successful
+'''	Examples:
+'''		oDoc.SetPrinter(Orientation := "PORTRAIT")
+
+Dim bPrinter As Boolean				'	Return value
+Dim vPrinters As Variant			'	Array of known printers
+Dim vOrientations As Variant		'	Array of allowed paper orientations
+Dim vPaperFormats As Variant		'	Array of allowed formats
+Dim vPrinterSettings As Variant		'	Array of property values
+Dim oPropertyValue As New com.sun.star.beans.PropertyValue
+									'	A single property value item
+Const cstThisSub = "SFDocuments.Document.SetPrinter"
+Const cstSubArgs = "[Printer=""""], [Orientation=""PORTRAIT""|""LANDSCAPE""]" _
+						& ", [PaperFormat=""A3""|""A4""|""A5""|""B4""|""B5""|""LETTER""|""LEGAL""|""TABLOID"""
+
+	If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
+	bPrinter = False
+
+Check:
+	If IsMissing(Printer) Or IsEmpty(Printer) Then Printer = ""
+	If IsMissing(Orientation) Or IsEmpty(Orientation) Then Orientation = ""
+	If IsMissing(PaperFormat) Or IsEmpty(PaperFormat) Then PaperFormat = ""
+	If IsMissing(_PrintComponent) Or IsEmpty(_PrintComponent) Then Set _PrintComponent = _Component
+	
+	ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs)		'	Unconditional validation
+	If Not _IsStillAlive() Then GoTo Finally
+	If VarType(Printer) = V_STRING Then
+		vPrinters = ScriptForge.SF_Platform.Printers
+		If Len(Printer) > 0 Then
+			If Not ScriptForge.SF_Utils._Validate(Printer, "Printer", V_STRING, vPrinters) Then GoTo Finally
+		End If
+	Else
+		If Not ScriptForge.SF_Utils._Validate(Printer, "Printer", V_STRING) Then GoTo Finally	'	Manage here the VarType error
+	End If
+	If VarType(Orientation) = V_STRING Then
+		vOrientations = Array("PORTRAIT", "LANDSCAPE")
+		If Len(Orientation) > 0 Then
+			If Not ScriptForge.SF_Utils._Validate(Orientation, "Orientation", V_STRING, vOrientations) Then GoTo Finally
+		End If
+	Else
+		If Not ScriptForge.SF_Utils._Validate(Orientation, "Orientation", V_STRING) Then GoTo Finally
+	End If
+	If VarType(PaperFormat) = V_STRING Then
+		vPaperFormats = Array("A3", "A4", "A5", "B4", "B5", "LETTER", "LEGAL", "TABLOID")
+		If Len(PaperFormat) > 0 Then
+			If Not ScriptForge.SF_Utils._Validate(PaperFormat, "PaperFormat", V_STRING, vPaperFormats) Then GoTo Finally
+		End If
+	Else
+		If Not ScriptForge.SF_Utils._Validate(PaperFormat, "PaperFormat", V_STRING) Then GoTo Finally
+	End If
+
+Try:
+	With _PrintComponent
+		Set oPropertyValue = ScriptForge.SF_Utils._MakePropertyValue("Name", Iif(Len(Printer) > 0, Printer, vPrinters(0)))
+		vPrinterSettings = Array(oPropertyValue)
+		If Len(Orientation) > 0 Then
+			vPrinterSettings = ScriptForge.SF_Utils._SetPropertyValue(vPrinterSettings, "PaperOrientation" _
+					, ScriptForge.SF_Array.IndexOf(vOrientations, Orientation, CaseSensitive := False))
+		End If
+		If Len(PaperFormat) > 0 Then
+			vPrinterSettings = ScriptForge.SF_Utils._SetPropertyValue(vPrinterSettings, "PaperFormat" _
+					, ScriptForge.SF_Array.IndexOf(vPaperFormats, PaperFormat, CaseSensitive := False))
+		End If
+		.setPrinter(vPrinterSettings)
+	End With
+	bPrinter = True
+
+Finally:
+	SetPrinter = bPrinter
+	ScriptForge.SF_Utils._ExitFunction(cstThisSub)
+	Exit Function
+Catch:
+	GoTo Finally
+End Function   '   SFDocuments.SF_Document.SetPrinter
+
+REM -----------------------------------------------------------------------------
 Private Function SetProperty(Optional ByVal psProperty As String _
 								, Optional ByVal pvValue As Variant _
 								) As Boolean
diff --git a/wizards/source/sfdocuments/SF_Writer.xba b/wizards/source/sfdocuments/SF_Writer.xba
index 2873f9057101..8a821112e78a 100644
--- a/wizards/source/sfdocuments/SF_Writer.xba
+++ b/wizards/source/sfdocuments/SF_Writer.xba
@@ -444,6 +444,14 @@ Public Function SaveCopyAs(Optional ByVal FileName As Variant _
 	SaveCopyAs = [_Super].SaveCopyAs(FileName, Overwrite, Password, FilterName, FilterOptions)
 End Function   '   SFDocuments.SF_Writer.SaveCopyAs
 
+REM -----------------------------------------------------------------------------
+Public Function SetPrinter(Optional ByVal Printer As Variant _
+							, Optional ByVal Orientation As Variant _
+							, Optional ByVal PaperFormat As Variant _
+							) As Boolean
+	SetPrinter = [_Super].SetPrinter(Printer, Orientation, PaperFormat)
+End Function	'   SFDocuments.SF_Writer.SetPrinter
+
 REM =========================================================== PRIVATE FUNCTIONS
 
 REM -----------------------------------------------------------------------------