ScriptForge (SF_Document) Echo() method freezes screen updates

While a script is executed any display update
resulting from that execution is done immediately.

For performance reasons it might be an advantage
to differ the display updates up to the end of the script.
This is where pairs of Echo() methods to set
and reset the removal of the immediate updates
may be beneficial.

Optionally the actual mouse pointer can be
modified to the image of an hourglass.

Arguments:
  EchoOn: when False, the display updates are suspended.
          Default = True.
          Multiple calls with EchoOn = False are harmless.
  Hourglass: when True, the mouse pointer is changed
          to an hourglass. Default = False.
          The mouse pointer needs to be inside the actual
          document's window.
          Note that it is very likely that at the least
          manual movement of the mouse, the operating system
          or the LibreOffice process will take back
          the control of the mouse icon and its usual behaviour.

The method may be called from any document, including Calc and
Writer, or form document.

It may be invoked from Basic and Python user scripts.

Echo() should be documented in the sfdocument.xhp help page.

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

5 files changed, 97 insertions, 0 deletions

diff --git a/wizards/source/scriptforge/python/scriptforge.py b/wizards/source/scriptforge/python/scriptforge.py
index 7abd8ff67716..a67dca437fd1 100644
--- a/wizards/source/scriptforge/python/scriptforge.py
+++ b/wizards/source/scriptforge/python/scriptforge.py
@@ -1993,6 +1993,9 @@ class SFDocuments:
         def CreateMenu(self, menuheader, before = '', submenuchar = '>'):
             return self.ExecMethod(self.vbMethod, 'CreateMenu', menuheader, before, submenuchar)
 
+        def Echo(self, echoon = True, hourglass = False):
+            return self.ExecMethod(self.vbMethod, 'Echo', echoon, hourglass)
+
         def ExportAsPDF(self, filename, overwrite = False, pages = '', password = '', watermark = ''):
             return self.ExecMethod(self.vbMethod, 'ExportAsPDF', filename, overwrite, pages, password, watermark)
 
diff --git a/wizards/source/sfdocuments/SF_Calc.xba b/wizards/source/sfdocuments/SF_Calc.xba
index bba5ebdf5b2e..dfd66fb5a2bf 100644
--- a/wizards/source/sfdocuments/SF_Calc.xba
+++ b/wizards/source/sfdocuments/SF_Calc.xba
@@ -3719,6 +3719,13 @@ Public Function CreateMenu(Optional ByVal MenuHeader As Variant _
 End Function	'	SFDocuments.SF_Calc.CreateMenu
 
 REM -----------------------------------------------------------------------------
+Public Sub Echo(Optional ByVal EchoOn As Variant _
+						, Optional ByVal Hourglass As Variant _
+						)
+	[_Super].Echo(EchoOn, Hourglass)
+End Sub		   '   SFDocuments.SF_Calc.Echo
+
+REM -----------------------------------------------------------------------------
 Public Function ExportAsPDF(Optional ByVal FileName As Variant _
 							, Optional ByVal Overwrite As Variant _
 							, Optional ByVal Pages As Variant _
diff --git a/wizards/source/sfdocuments/SF_Document.xba b/wizards/source/sfdocuments/SF_Document.xba
index 03fb215369ea..879d90c0cfef 100644
--- a/wizards/source/sfdocuments/SF_Document.xba
+++ b/wizards/source/sfdocuments/SF_Document.xba
@@ -539,6 +539,78 @@ Catch:
 End Function   '   SFDocuments.SF_Document.CreateMenu
 
 REM -----------------------------------------------------------------------------
+Public Sub Echo(Optional ByVal EchoOn As Variant _
+						, Optional ByVal Hourglass As Variant _
+						)
+'''	While a script is executed any display update resulting from that execution
+'''	is done immediately.
+'''	For performance reasons it might be an advantage to differ the display updates
+'''	up to the end of the script.
+'''	This is where pairs of Echo() methods to set and reset the removal of the
+'''	immediate updates may be beneficial.
+'''	Optionally the actual mouse pointer can be modified to the image of an hourglass.
+'''	Args:
+'''		EchoOn: when False, the display updates are suspended. Default = True.
+'''			Multiple calls with EchoOn = False are harmless.
+'''		Hourglass: when True, the mouse pointer is changed to an hourglass. Default = False.
+'''			The mouse pointer needs to be inside the actual document's window.
+'''			Note that it is very likely that at the least manual movement of the mouse,
+'''			the operating system or the LibreOffice process will take back the control
+'''			of the mouse icon and its usual behaviour.
+'''	Returns:
+'''	Examples:
+'''		oDoc.Echo(False, Hourglass := True)
+'''		'	... "long-lasting" script ...
+'''		oDoc.Echo()			'	Reset to normal
+
+Dim oContainer As Object		'	com.sun.star.awt.XWindow
+Dim lPointer As Long			'	com.sun.star.awt.SystemPointer constant
+Dim oPointer As Object			'	com.sun.star.awt.Pointer
+Const cstThisSub = "SFDocuments.Document.Echo"
+Const cstSubArgs = "[EchoOn=True], [Hourglass=False]"
+
+	If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
+
+Check:
+	If IsMissing(EchoOn) Or IsEmpty(EchoOn) Then EchoOn = True
+	If IsMissing(Hourglass) Or IsEmpty(Hourglass) Then Hourglass = False
+	If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
+		If Not _IsStillAlive() Then GoTo Finally
+		If Not SF_Utils._Validate(EchoOn, "EchoOn", ScriptForge.V_BOOLEAN) Then GoTo Finally
+		If Not SF_Utils._Validate(Hourglass, "Hourglass", ScriptForge.V_BOOLEAN) Then GoTo Finally
+	End If
+
+Try:
+	With _Component
+
+		Set oContainer = .CurrentController.Frame.GetContainerWindow()
+		Set oPointer = CreateUnoService("com.sun.star.awt.Pointer")
+		With com.sun.star.awt.SystemPointer
+			If Hourglass Then lPointer = .WAIT Else lPointer = .ARROW
+		End With
+		oPointer.setType(lPointer)
+
+		'	Mouse icon is set when controller is unlocked
+		If Not EchoOn Then
+			oContainer.setPointer(oPointer)
+			.lockControllers()
+		Else			'	EchoOn = True
+			Do While .hasControllersLocked()
+				.unlockControllers()
+			Loop
+			oContainer.setPointer(oPointer)
+		End If
+
+	End With
+
+Finally:
+	ScriptForge.SF_Utils._ExitFunction(cstThisSub)
+	Exit Sub
+Catch:
+	GoTo Finally	
+End Sub			'	SFDocuments.SF_Document.Echo
+
+REM -----------------------------------------------------------------------------
 Public Function ExportAsPDF(Optional ByVal FileName As Variant _
 							, Optional ByVal Overwrite As Variant _
 							, Optional ByVal Pages As Variant _
@@ -679,6 +751,7 @@ Public Function Methods() As Variant
 					"Activate" _
 					, "CloseDocument" _
 					, "CreateMenu" _
+					, "Echo" _
 					, "ExportAsPDF" _
 					, "PrintOut" _
 					, "RemoveMenu" _
diff --git a/wizards/source/sfdocuments/SF_FormDocument.xba b/wizards/source/sfdocuments/SF_FormDocument.xba
index 8d13d86e96e4..f0dfa51d6a97 100644
--- a/wizards/source/sfdocuments/SF_FormDocument.xba
+++ b/wizards/source/sfdocuments/SF_FormDocument.xba
@@ -489,6 +489,13 @@ Public Function CreateMenu(Optional ByVal MenuHeader As Variant _
 End Function	'	SFDocuments.SF_FormDocument.CreateMenu
 
 REM -----------------------------------------------------------------------------
+Public Sub Echo(Optional ByVal EchoOn As Variant _
+						, Optional ByVal Hourglass As Variant _
+						)
+	[_Super].Echo(EchoOn, Hourglass)
+End Sub		   '   SFDocuments.SF_FormDocument.Echo
+
+REM -----------------------------------------------------------------------------
 Public Function ExportAsPDF(Optional ByVal FileName As Variant _
 							, Optional ByVal Overwrite As Variant _
 							, Optional ByVal Pages As Variant _
diff --git a/wizards/source/sfdocuments/SF_Writer.xba b/wizards/source/sfdocuments/SF_Writer.xba
index 6f3f258dcb75..d19b18d5c98f 100644
--- a/wizards/source/sfdocuments/SF_Writer.xba
+++ b/wizards/source/sfdocuments/SF_Writer.xba
@@ -513,6 +513,13 @@ Public Function CreateMenu(Optional ByVal MenuHeader As Variant _
 End Function	'	SFDocuments.SF_Writer.CreateMenu
 
 REM -----------------------------------------------------------------------------
+Public Sub Echo(Optional ByVal EchoOn As Variant _
+						, Optional ByVal Hourglass As Variant _
+						)
+	[_Super].Echo(EchoOn, Hourglass)
+End Sub		   '   SFDocuments.SF_Writer.Echo
+
+REM -----------------------------------------------------------------------------
 Public Function ExportAsPDF(Optional ByVal FileName As Variant _
 							, Optional ByVal Overwrite As Variant _
 							, Optional ByVal Pages As Variant _