ScriptForge - (SFDocuments) new PrintOut() method

The PrintOut() method launches the printing of a
LO document to a printer previously defined by default,
by the user or by the SetPrinter() method.

It is applicable on any document, on a Calc sheet, a Base form
document. For a Writer document specific arguments may
be provided.

Implemented both for Basic and Python user scripts.

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

5 files changed, 267 insertions, 0 deletions

diff --git a/wizards/source/scriptforge/python/scriptforge.py b/wizards/source/scriptforge/python/scriptforge.py
index 1d7bd96fa2c5..5e3b2c6c7a8c 100644
--- a/wizards/source/scriptforge/python/scriptforge.py
+++ b/wizards/source/scriptforge/python/scriptforge.py
@@ -1748,6 +1748,9 @@ class SFDocuments:
         def CloseDocument(self, saveask = True):
             return self.ExecMethod(self.vbMethod, 'CloseDocument', saveask)
 
+        def PrintOut(self, pages = '', copies = 1):
+            return self.ExecMethod(self.vbMethod, 'PrintOut', pages, copies)
+
         def RunCommand(self, command):
             return self.ExecMethod(self.vbMethod, 'RunCommand', command)
 
@@ -1806,6 +1809,9 @@ class SFDocuments:
         def OpenFormDocument(self, formdocument, designmode = False):
             return self.ExecMethod(self.vbMethod, 'OpenFormDocument', formdocument, designmode)
 
+        def PrintOut(self, formdocument, pages = '', copies = 1):
+            return self.ExecMethod(self.vbMethod, 'PrintOut', formdocument, pages, copies)
+
         def SetPrinter(self, formdocument = '', printer = '', orientation = '', paperformat = ''):
             return self.ExecMethod(self.vbMethod, 'SetPrinter', formdocument, printer, orientation, paperformat)
 
@@ -1945,6 +1951,9 @@ class SFDocuments:
                    width = ScriptForge.cstSymEmpty):
             return self.ExecMethod(self.vbMethod, 'Offset', range, rows, columns, height, width)
 
+        def PrintOut(self, sheetname = '~', pages = '', copies = 1):
+            return self.ExecMethod(self.vbMethod, 'PrintOut', sheetname, pages, copies)
+
         def RemoveSheet(self, sheetname):
             return self.ExecMethod(self.vbMethod, 'RemoveSheet', sheetname)
 
@@ -2103,6 +2112,11 @@ class SFDocuments:
         def Forms(self, form = ''):
             return self.ExecMethod(self.vbMethod + self.flgArrayRet, 'Forms', form)
 
+        def PrintOut(self, pages = '', copies = 1, printbackground = True, printblankpages = False,
+                     printevenpages = True, printoddpages = True, printimages = True):
+            return self.ExecMethod(self.vbMethod, 'PrintOut', pages, copies, printbackground, printblankpages,
+                                   printevenpages, printoddpages, printimages)
+
 
 # ##############################################False##################################################################
 #                           CreateScriptService()                                                                   ###
diff --git a/wizards/source/sfdocuments/SF_Base.xba b/wizards/source/sfdocuments/SF_Base.xba
index 7ed8360c4fd0..52fc0fd768c2 100644
--- a/wizards/source/sfdocuments/SF_Base.xba
+++ b/wizards/source/sfdocuments/SF_Base.xba
@@ -404,10 +404,12 @@ Public Function Methods() As Variant
 					, "GetDatabase" _
 					, "IsLoaded" _
 					, "OpenFormDocument" _
+					, "PrintOut" _
 					, "RunCommand" _
 					, "Save" _
 					, "SaveAs" _
 					, "SaveCopyAs" _
+					, "SetPrinter" _
 					)
 
 End Function	'	SFDocuments.SF_Base.Methods
@@ -470,6 +472,64 @@ Catch:
 End Function	'	SFDocuments.SF_Base.OpenFormDocument
 
 REM -----------------------------------------------------------------------------
+Public Function PrintOut(Optional ByVal FormDocument As Variant _
+							, Optional ByVal Pages As Variant _
+							, Optional ByVal Copies As Variant _
+							) As Boolean
+''' Send the content of the given form document to the printer.
+'''	The printer might be defined previously by default, by the user or by the SetPrinter() method
+'''	The given form document must be open. It is activated by the method.
+'''	Args:
+'''		FormDocument: a valid document form name as a case-sensitive string
+'''		Pages: the pages to print as a string, like in the user interface. Example: "1-4;10;15-18". Default = all pages
+'''		Copies: the number of copies
+'''	Exceptions:
+'''		FORMDEADERROR			The form is not open
+'''	Returns:
+'''		True when successful
+'''	Examples:
+'''		oDoc.PrintOut("myForm", "1-4;10;15-18", Copies := 2)
+
+Dim bPrint As Boolean				'	Return value
+Dim vFormNames As Variant			'	Array of all document form names present in the document
+Dim oFormDocument As Object			'	com.sun.star.comp.sdb.Content
+
+Const cstThisSub = "SFDocuments.Base.PrintOut"
+Const cstSubArgs = "FormDocument, [Pages=""""], [Copies=1]"
+
+	If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
+	bPrint = False
+
+Check:
+	If IsMissing(Pages) Or IsEmpty(Pages) Then Pages = ""
+	If IsMissing(Copies) Or IsEmpty(Copies) Then Copies = 1
+	
+	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()
+		vFormNames = Split(_CollectFormDocuments(_FormDocuments), cstToken)
+		If Not ScriptForge.SF_Utils._Validate(FormDocument, "FormDocument", V_STRING, vFormNames) Then GoTo Finally
+		If Not ScriptForge.SF_Utils._Validate(Pages, "Pages", V_STRING) Then GoTo Finally
+		If Not ScriptForge.SF_Utils._Validate(Copies, "Copies", ScriptForge.V_NUMERIC) Then GoTo Finally
+	End If
+	If Not IsLoaded(FormDocument) Then GoTo CatchClosed
+
+Try:
+	Set oFormDocument = _FormDocuments.getByHierarchicalName(FormDocument)
+	bPrint = [_Super].PrintOut(Pages, Copies, oFormDocument.Component)
+
+Finally:
+	PrintOut = bPrint
+	ScriptForge.SF_Utils._ExitFunction(cstThisSub)
+	Exit Function
+Catch:
+	GoTo Finally
+CatchClosed:
+	ScriptForge.SF_Exception.RaiseFatal(FORMDEADERROR, FormDocument, _FileIdent())
+End Function   '   SFDocuments.SF_Base.PrintOut
+
+REM -----------------------------------------------------------------------------
 Public Function Properties() As Variant
 '''	Return the list or properties of the Base class as an array
 
diff --git a/wizards/source/sfdocuments/SF_Calc.xba b/wizards/source/sfdocuments/SF_Calc.xba
index f5247088d2a2..b5a491915ceb 100644
--- a/wizards/source/sfdocuments/SF_Calc.xba
+++ b/wizards/source/sfdocuments/SF_Calc.xba
@@ -1361,6 +1361,7 @@ Public Function Methods() As Variant
 					, "MoveRange" _
 					, "MoveSheet" _
 					, "Offset" _
+					, "PrintOut" _
 					, "RemoveSheet" _
 					, "RenameSheet" _
 					, "RunCommand" _
@@ -1370,6 +1371,7 @@ Public Function Methods() As Variant
 					, "SetArray" _
 					, "SetCellStyle" _
 					, "SetFormula" _
+					, "SetPrinter" _
 					, "SetValue" _
 					, "SortRange" _
 					)
@@ -1554,6 +1556,63 @@ Catch:
 End Function	'	SF_Documents.SF_Calc.Offset
 
 REM -----------------------------------------------------------------------------
+Public Function PrintOut(Optional ByVal SheetName As Variant _
+							, Optional ByVal Pages As Variant _
+							, Optional ByVal Copies As Variant _
+							) As Boolean
+''' Send the content of the given sheet to the printer.
+'''	The printer might be defined previously by default, by the user or by the SetPrinter() method
+'''	Args:
+'''		SheetName: the sheet to print. Default = the active sheet
+'''		Pages: the pages to print as a string, like in the user interface. Example: "1-4;10;15-18". Default = all pages
+'''		Copies: the number of copies
+'''	Returns:
+'''		True when successful
+'''	Examples:
+'''		oDoc.PrintOut("SheetX", "1-4;10;15-18", Copies := 2)
+
+Dim bPrint As Boolean				'	Return value
+Dim oSheet As Object				'	SheetName as a reference
+
+Const cstThisSub = "SFDocuments.Calc.PrintOut"
+Const cstSubArgs = "[SheetName=""~""], [Pages=""""], [Copies=1]"
+
+	If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
+	bPrint = False
+
+Check:
+	If IsMissing(SheetName) Or IsEmpty(SheetName) Then SheetName = ""
+	If IsMissing(Pages) Or IsEmpty(Pages) Then Pages = ""
+	If IsMissing(Copies) Or IsEmpty(Copies) Then Copies = 1
+	
+	If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
+		If Not _IsStillAlive() Then GoTo Finally
+		If Not _ValidateSheet(SheetName, "SheetName", , True, True) Then GoTo Finally
+		If Not ScriptForge.SF_Utils._Validate(Pages, "Pages", V_STRING) Then GoTo Finally
+		If Not ScriptForge.SF_Utils._Validate(Copies, "Copies", ScriptForge.V_NUMERIC) Then GoTo Finally
+	End If
+
+Try:
+	If SheetName = "~" Then SheetName = ""
+	'	Make given sheet active
+	If Len(SheetName) > 0 Then
+		With _Component
+			Set oSheet = .getSheets.getByName(SheetName)
+			Set .CurrentController.ActiveSheet = oSheet
+		End With
+	End If
+
+	bPrint = [_Super].PrintOut(Pages, Copies, _Component)
+
+Finally:
+	PrintOut = bPrint
+	ScriptForge.SF_Utils._ExitFunction(cstThisSub)
+	Exit Function
+Catch:
+	GoTo Finally
+End Function   '   SFDocuments.SF_Calc.PrintOut
+
+REM -----------------------------------------------------------------------------
 Public Function Properties() As Variant
 '''	Return the list or properties of the Calc class as an array
 
diff --git a/wizards/source/sfdocuments/SF_Document.xba b/wizards/source/sfdocuments/SF_Document.xba
index 85eafb39dd84..40c39822d531 100644
--- a/wizards/source/sfdocuments/SF_Document.xba
+++ b/wizards/source/sfdocuments/SF_Document.xba
@@ -500,15 +500,72 @@ Public Function Methods() As Variant
 	Methods = Array( _
 					"Activate" _
 					, "CloseDocument" _
+					, "PrintOut" _
 					, "RunCommand" _
 					, "Save" _
 					, "SaveAs" _
 					, "SaveCopyAs" _
+					, "SetPrinter" _
 					)
 
 End Function	'	SFDocuments.SF_Document.Methods
 
 REM -----------------------------------------------------------------------------
+Public Function PrintOut(Optional ByVal Pages As Variant _
+							, Optional ByVal Copies As Variant _
+							, Optional ByRef _Document As Variant _
+							) As Boolean
+''' Send the content of the document to the printer.
+'''	The printer might be defined previously by default, by the user or by the SetPrinter() method
+'''	Args:
+'''		Pages: the pages to print as a string, like in the user interface. Example: "1-4;10;15-18". Default = all pages
+'''		Copies: the number of copies
+'''		_Document: undocumented argument to designate the document to print when called from a subclass
+'''	Returns:
+'''		True when successful
+'''	Examples:
+'''		oDoc.PrintOut("1-4;10;15-18", Copies := 2)
+
+Dim bPrint As Boolean				'	Return value
+Dim vPrintGoal As Variant			'	Array of property values
+
+Const cstThisSub = "SFDocuments.Document.PrintOut"
+Const cstSubArgs = "[Pages=""""], [Copies=1]"
+
+	If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
+	bPrint = False
+
+Check:
+	If IsMissing(Pages) Or IsEmpty(Pages) Then Pages = ""
+	If IsMissing(Copies) Or IsEmpty(Copies) Then Copies = 1
+	If IsMissing(_Document) Or IsEmpty(_Document) Or IsNull(_Document) Then Set _Document = _Component
+	
+	If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
+		If Not _IsStillAlive() Then GoTo Finally
+		If Not ScriptForge.SF_Utils._Validate(Pages, "Pages", V_STRING) Then GoTo Finally
+		If Not ScriptForge.SF_Utils._Validate(Copies, "Copies", ScriptForge.V_NUMERIC) Then GoTo Finally
+	End If
+
+Try:
+	vPrintGoal = Array( _
+						ScriptForge.SF_Utils._MakePropertyValue("CopyCount", CInt(Copies)) _
+						, ScriptForge.SF_Utils._MakePropertyValue("Collate", True) _
+						, ScriptForge.SF_Utils._MakePropertyValue("Pages", Pages) _
+						, ScriptForge.SF_Utils._MakePropertyValue("Wait", False) _
+						)
+
+	_Document.Print(vPrintGoal)
+	bPrint = True
+
+Finally:
+	PrintOut = bPrint
+	ScriptForge.SF_Utils._ExitFunction(cstThisSub)
+	Exit Function
+Catch:
+	GoTo Finally
+End Function   '   SFDocuments.SF_Document.PrintOut
+
+REM -----------------------------------------------------------------------------
 Public Function Properties() As Variant
 '''	Return the list or properties of the Document class as an array
 
diff --git a/wizards/source/sfdocuments/SF_Writer.xba b/wizards/source/sfdocuments/SF_Writer.xba
index 8a821112e78a..7d839c7b5ba6 100644
--- a/wizards/source/sfdocuments/SF_Writer.xba
+++ b/wizards/source/sfdocuments/SF_Writer.xba
@@ -220,15 +220,92 @@ Public Function Methods() As Variant
 					"Activate" _
 					, "CloseDocument" _
 					, "Forms" _
+					, "PrintOut" _
 					, "RunCommand" _
 					, "Save" _
 					, "SaveAs" _
 					, "SaveCopyAs" _
+					, "SetPrinter" _
 					)
 
 End Function	'	SFDocuments.SF_Writer.Methods
 
 REM -----------------------------------------------------------------------------
+Public Function PrintOut(Optional ByVal Pages As Variant _
+							, Optional ByVal Copies As Variant _
+							, Optional ByVal PrintBackground As Variant _
+							, Optional ByVal PrintBlankPages As Variant _
+							, Optional ByVal PrintEvenPages As Variant _
+							, Optional ByVal PrintOddPages As Variant _
+							, Optional ByVal PrintImages As Variant _
+							) As Boolean
+''' Send the content of the document to the printer.
+'''	The printer might be defined previously by default, by the user or by the SetPrinter() method
+'''	Args:
+'''		Pages: the pages to print as a string, like in the user interface. Example: "1-4;10;15-18". Default = all pages
+'''		Copies: the number of copies
+'''		PrintBackground: print the background image when True (default)
+'''		PrintBlankPages: when False (default), omit empty pages
+'''		PrintEvenPages: print the left pages when True (default)
+'''		PrintOddPages: print the right pages when True (default)
+'''		PrintImages: print the graphic objects when True (default)
+'''	Returns:
+'''		True when successful
+'''	Examples:
+'''		oDoc.PrintOut("1-4;10;15-18", Copies := 2, PrintImages := False)
+
+Dim bPrint As Boolean				'	Return value
+Dim vPrintOptions As Variant		'	com.sun.star.text.DocumentSettings
+
+Const cstThisSub = "SFDocuments.Writer.PrintOut"
+Const cstSubArgs = "[Pages=""""], [Copies=1], [PrintBackground=True], [PrintBlankPages=False], [PrintEvenPages=True]" _
+						& ", [PrintOddPages=True], [PrintImages=True]"
+
+	If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
+	bPrint = False
+
+Check:
+	If IsMissing(Pages) Or IsEmpty(Pages) Then Pages = ""
+	If IsMissing(Copies) Or IsEmpty(Copies) Then Copies = 1
+	If IsMissing(PrintBackground) Or IsEmpty(PrintBackground) Then PrintBackground = True
+	If IsMissing(PrintBlankPages) Or IsEmpty(PrintBlankPages) Then PrintBlankPages = False
+	If IsMissing(PrintEvenPages) Or IsEmpty(PrintEvenPages) Then PrintEvenPages = True
+	If IsMissing(PrintOddPages) Or IsEmpty(PrintOddPages) Then PrintOddPages = True
+	If IsMissing(PrintImages) Or IsEmpty(PrintImages) Then PrintImages = True
+	
+	If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
+		If Not _IsStillAlive() Then GoTo Finally
+		If Not ScriptForge.SF_Utils._Validate(Pages, "Pages", V_STRING) Then GoTo Finally
+		If Not ScriptForge.SF_Utils._Validate(Copies, "Copies", ScriptForge.V_NUMERIC) Then GoTo Finally
+		If Not ScriptForge.SF_Utils._Validate(PrintBackground, "PrintBackground", ScriptForge.V_BOOLEAN) Then GoTo Finally
+		If Not ScriptForge.SF_Utils._Validate(PrintBlankPages, "PrintBlankPages", ScriptForge.V_BOOLEAN) Then GoTo Finally
+		If Not ScriptForge.SF_Utils._Validate(PrintEvenPages, "PrintEvenPages", ScriptForge.V_BOOLEAN) Then GoTo Finally
+		If Not ScriptForge.SF_Utils._Validate(PrintOddPages, "PrintOddPages", ScriptForge.V_BOOLEAN) Then GoTo Finally
+		If Not ScriptForge.SF_Utils._Validate(PrintImages, "PrintImages", ScriptForge.V_BOOLEAN) Then GoTo Finally
+	End If
+
+Try:
+	vPrintOptions = _Component.createInstance("com.sun.star.text.DocumentSettings")
+	With vPrintOptions
+		.PrintPageBackground = PrintBackground
+		.PrintEmptyPages = PrintBlankPages
+		.PrintLeftPages = PrintEvenPages
+		.PrintRightPages = PrintOddPages
+		.PrintGraphics = PrintImages
+		.PrintDrawings = PrintImages
+	End With
+
+	bPrint = [_Super].PrintOut(Pages, Copies, _Component)
+
+Finally:
+	PrintOut = bPrint
+	ScriptForge.SF_Utils._ExitFunction(cstThisSub)
+	Exit Function
+Catch:
+	GoTo Finally
+End Function   '   SFDocuments.SF_Writer.PrintOut
+
+REM -----------------------------------------------------------------------------
 Public Function Properties() As Variant
 '''	Return the list or properties of the Writer class as an array