ScriptForge - (SFWidgets) new SF_Menu service

Display a menu in the menubar of a document (form document to be done)
After use, the menu will not be saved neither in the application settings,
nor in the document. The menu setting does not affect the modified status of the
document.

The menu will be displayed, as usual, when its header in the menubar is clicked.
When one of its items is selected, there are 3 alternative options:
- a UNO command (like ".uno:About") is triggered
- a user script is run receiving a standard argument defined in this service
- one of above combined with a toggle of the status of the item

The menu is described from top to bottom.
Each menu item receives a numeric and a string identifier.
Each menu item may be decorated with a tooltip and/or an icon.

The AddItem(), AddCheckBox() and AddRadioButton() methods, when
coompared with their equivalents in the SF_PopupMenu service,
receive 2 additional arguments: Command and Script.

The various document services receive 2 additional methods:
CreateMenu(), returning a Menu service instance
RemoveMenu()

Very short example:
menu = doc.CreateMenu("My menu", Before := "Help")
menu.AddItem("First Item", Command := "About")
menu.AddItem('2nd Item", Script := "... URI notation ...")
menu.Dispose()   '   Once set the menu object may ve erased, listeners stay tuned
Later in the lifecycle of the document, one may run:
doc.RemoveMenu("My menu")   '  doc.RemoveMenu("File") works as well !!!

All the functionalities are available both in Basic and Python user scripts.

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

4 files changed, 180 insertions, 8 deletions

diff --git a/wizards/source/sfdocuments/SF_Base.xba b/wizards/source/sfdocuments/SF_Base.xba
index efdc57be9b4d..0199341bb5da 100644
--- a/wizards/source/sfdocuments/SF_Base.xba
+++ b/wizards/source/sfdocuments/SF_Base.xba
@@ -120,7 +120,7 @@ Check:
 	If IsMissing(SaveAsk) Or IsEmpty(SaveAsk) Then SaveAsk = True
 	If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
 		If Not _IsStillAlive(True) Then GoTo Finally
-		If Not ScriptForge.SF_Utils._Validate(SaveAsk, "SaveAsk", V_BOOLEAN) Then GoTo Finally
+		If Not ScriptForge.SF_Utils._Validate(SaveAsk, "SaveAsk", ScriptForge.V_BOOLEAN) Then GoTo Finally
 	End If
 
 Try:
@@ -442,12 +442,15 @@ Public Function Methods() As Variant
 	Methods = Array( _
 					"Activate" _
 					, "CloseDocument" _
+					, "CloseFormDocument" _
+					, "CreateMenu" _
 					, "FormDocuments" _
 					, "Forms" _
 					, "GetDatabase" _
 					, "IsLoaded" _
 					, "OpenFormDocument" _
 					, "PrintOut" _
+					, "RemoveMenu" _
 					, "RunCommand" _
 					, "Save" _
 					, "SaveAs" _
@@ -792,6 +795,19 @@ Public Function Activate() As Boolean
 End Function    '   SFDocuments.SF_Base.Activate
 
 REM -----------------------------------------------------------------------------
+Public Function CreateMenu(Optional ByVal MenuHeader As Variant _
+								, Optional ByVal Before As Variant _
+								, Optional ByVal SubmenuChar As Variant _
+								) As Object
+	Set CreateMenu = [_Super].CreateMenu(MenuHeader, Before, SubmenuChar)
+End Function	'	SFDocuments.SF_Base.CreateMenu
+
+REM -----------------------------------------------------------------------------
+Public Function RemoveMenu(Optional ByVal MenuHeader As Variant) As Boolean
+	RemoveMenu = [_Super].RemoveMenu(MenuHeader)
+End Function	'	SFDocuments.SF_Base.RemoveMenu
+
+REM -----------------------------------------------------------------------------
 Public Sub RunCommand(Optional ByVal Command As Variant)
 	[_Super].RunCommand(Command)
 End Sub		  '   SFDocuments.SF_Base.RunCommand
diff --git a/wizards/source/sfdocuments/SF_Calc.xba b/wizards/source/sfdocuments/SF_Calc.xba
index e5b35e4afa12..f22a64642e36 100644
--- a/wizards/source/sfdocuments/SF_Calc.xba
+++ b/wizards/source/sfdocuments/SF_Calc.xba
@@ -1647,6 +1647,7 @@ Public Function Methods() As Variant
 					, "CopyToCell" _
 					, "CopyToRange" _
 					, "CreateChart" _
+					, "CreateMenu" _
 					, "DAvg" _
 					, "DCount" _
 					, "DMax" _
@@ -1665,6 +1666,7 @@ Public Function Methods() As Variant
 					, "OpenRangeSelector" _
 					, "Printf" _
 					, "PrintOut" _
+					, "RemoveMenu" _
 					, "RemoveSheet" _
 					, "RenameSheet" _
 					, "RunCommand" _
@@ -2889,9 +2891,9 @@ Check:
 		If Not ScriptForge.SF_Utils._ValidateArray(SortKeys, "SortKeys", 1, V_NUMERIC, True) Then GoTo Finally
 		If Not ScriptForge.SF_Utils._Validate(DestinationCell, "DestinationCell", V_STRING) Then GoTo Finally
 		If Not ScriptForge.SF_Utils._ValidateArray(SortOrder, "SortOrder", 1, V_STRING, True) Then GoTo Finally
-		If Not ScriptForge.SF_Utils._Validate(ContainsHeader, "ContainsHeader", V_BOOLEAN) Then GoTo Finally
-		If Not ScriptForge.SF_Utils._Validate(CaseSensitive, "CaseSensitive", V_BOOLEAN) Then GoTo Finally
-		If Not ScriptForge.SF_Utils._Validate(SortColumns, "SortColumns", V_BOOLEAN) Then GoTo Finally
+		If Not ScriptForge.SF_Utils._Validate(ContainsHeader, "ContainsHeader", ScriptForge.V_BOOLEAN) Then GoTo Finally
+		If Not ScriptForge.SF_Utils._Validate(CaseSensitive, "CaseSensitive", ScriptForge.V_BOOLEAN) Then GoTo Finally
+		If Not ScriptForge.SF_Utils._Validate(SortColumns, "SortColumns", ScriptForge.V_BOOLEAN) Then GoTo Finally
 	End If
 	Set oRangeAddress = _ParseAddress(Range)
 	If Len(DestinationCell) > 0 Then Set oDestRange = _ParseAddress(DestinationCell)
@@ -3068,6 +3070,14 @@ Public Function CloseDocument(Optional ByVal SaveAsk As Variant) As Boolean
 End Function   '   SFDocuments.SF_Calc.CloseDocument
 
 REM -----------------------------------------------------------------------------
+Public Function CreateMenu(Optional ByVal MenuHeader As Variant _
+								, Optional ByVal Before As Variant _
+								, Optional ByVal SubmenuChar As Variant _
+								) As Object
+	Set CreateMenu = [_Super].CreateMenu(MenuHeader, Before, SubmenuChar)
+End Function	'	SFDocuments.SF_Calc.CreateMenu
+
+REM -----------------------------------------------------------------------------
 Public Function ExportAsPDF(Optional ByVal FileName As Variant _
 							, Optional ByVal Overwrite As Variant _
 							, Optional ByVal Pages As Variant _
@@ -3078,6 +3088,11 @@ Public Function ExportAsPDF(Optional ByVal FileName As Variant _
 End Function   '   SFDocuments.SF_Calc.ExportAsPDF
 
 REM -----------------------------------------------------------------------------
+Public Function RemoveMenu(Optional ByVal MenuHeader As Variant) As Boolean
+	RemoveMenu = [_Super].RemoveMenu(MenuHeader)
+End Function	'	SFDocuments.SF_Calc.RemoveMenu
+
+REM -----------------------------------------------------------------------------
 Public Sub RunCommand(Optional ByVal Command As Variant)
 	[_Super].RunCommand(Command)
 End Sub		  '   SFDocuments.SF_Calc.RunCommand
diff --git a/wizards/source/sfdocuments/SF_Document.xba b/wizards/source/sfdocuments/SF_Document.xba
index 00aa22fc08b4..37c4e4e6bbe7 100644
--- a/wizards/source/sfdocuments/SF_Document.xba
+++ b/wizards/source/sfdocuments/SF_Document.xba
@@ -436,7 +436,7 @@ Check:
 	If IsMissing(SaveAsk) Or IsEmpty(SaveAsk) Then SaveAsk = True
 	If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
 		If Not _IsStillAlive() Then GoTo Finally
-		If Not ScriptForge.SF_Utils._Validate(SaveAsk, "SaveAsk", V_BOOLEAN) Then GoTo Finally
+		If Not ScriptForge.SF_Utils._Validate(SaveAsk, "SaveAsk", ScriptForge.V_BOOLEAN) Then GoTo Finally
 	End If
 
 Try:
@@ -460,6 +460,63 @@ Catch:
 End Function   '   SFDocuments.SF_Document.CloseDocument
 
 REM -----------------------------------------------------------------------------
+Public Function CreateMenu(Optional ByVal MenuHeader As Variant _
+								, Optional ByVal Before As Variant _
+								, Optional ByVal SubmenuChar As Variant _
+								, Optional ByRef _Document As Variant _
+								) As Object
+''' Create a new menu entry in the document's menubar
+'''	The menu is not intended to be saved neither in the LibreOffice global environment, nor in the document
+'''	The method returns a SFWidgets.Menu instance. Its methods let define the menu further.
+'''	Args:
+'''		MenuHeader: the name/header of the menu
+'''		Before: the place where to put the new menu on the menubar (string or number >= 1)
+'''			When not found => last position
+'''		SubmenuChar: the delimiter used in menu trees. Default = ">"
+'''		_Document: undocumented argument to designate the document where the menu will be located
+'''	Returns:
+'''		A SFWidgets.Menu instance or Nothing
+'''	Examples:
+'''		Dim oMenu As Object
+'''		Set oMenu = oDoc.CreateMenu("My menu", Before := "Styles")
+'''		With oMenu
+'''			.AddItem("Item 1", Command := "About")
+'''			'...
+'''			.Dispose()	'	When definition is complete, the menu instance may be disposed
+'''		End With
+'''			' ...
+
+Dim oMenu As Object			'	return value
+Const cstThisSub = "SFDocuments.Document.CreateMenu"
+Const cstSubArgs = "MenuHeader, [Before=""""], [SubmenuChar="">""]"
+
+	If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
+	Set oMenu = Nothing
+
+Check:
+	If IsMissing(Before) Or IsEmpty(Before) Then Before = ""
+	If IsMissing(SubmenuChar) Or IsEmpty(SubmenuChar) Then SubmenuChar = ""
+	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(MenuHeader, "MenuHeader", V_STRING) Then GoTo Finally
+		If Not ScriptForge.SF_Utils._Validate(Before, "Before", V_STRING) Then GoTo Finally
+		If Not ScriptForge.SF_Utils._Validate(SubmenuChar, "SubmenuChar", V_STRING) Then GoTo Finally
+	End If
+
+Try:
+	Set oMenu = ScriptForge.SF_Services.CreateScriptService("SFWidgets.Menu", _Document, MenuHeader, Before, SubmenuChar)
+
+Finally:
+	Set CreateMenu = oMenu
+	ScriptForge.SF_Utils._ExitFunction(cstThisSub)
+	Exit Function
+Catch:
+	GoTo Finally
+End Function   '   SFDocuments.SF_Document.CreateMenu
+
+REM -----------------------------------------------------------------------------
 Public Function ExportAsPDF(Optional ByVal FileName As Variant _
 							, Optional ByVal Overwrite As Variant _
 							, Optional ByVal Pages As Variant _
@@ -502,7 +559,7 @@ Check:
 	If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
 		If Not _IsStillAlive() Then GoTo Finally
 		If Not SF_Utils._ValidateFile(FileName, "FileName") Then GoTo Finally
-		If Not SF_Utils._Validate(Overwrite, "Overwrite", V_BOOLEAN) Then GoTo Finally
+		If Not SF_Utils._Validate(Overwrite, "Overwrite", ScriptForge.V_BOOLEAN) Then GoTo Finally
 		If Not SF_Utils._Validate(Pages, "Pages", V_STRING) Then GoTo Finally
 		If Not SF_Utils._Validate(Password, "Password", V_STRING) Then GoTo Finally
 		If Not SF_Utils._Validate(Watermark, "Watermark", V_STRING) Then GoTo Finally
@@ -596,8 +653,10 @@ Public Function Methods() As Variant
 	Methods = Array( _
 					"Activate" _
 					, "CloseDocument" _
+					, "CreateMenu" _
 					, "ExportAsPDF" _
 					, "PrintOut" _
+					, "RemoveMenu" _
 					, "RunCommand" _
 					, "Save" _
 					, "SaveAs" _
@@ -687,6 +746,73 @@ Public Function Properties() As Variant
 End Function	'	SFDocuments.SF_Document.Properties
 
 REM -----------------------------------------------------------------------------
+Public Function RemoveMenu(Optional ByVal MenuHeader As Variant _
+							, Optional ByRef _Document As Variant _
+) As Boolean
+''' Remove a menu entry in the document's menubar
+'''	The removal is not intended to be saved neither in the LibreOffice global environment, nor in the document
+'''	Args:
+'''		MenuHeader: the name/header of the menu, without tilde "~", as a case-sensitive string
+'''		_Document: undocumented argument to designate the document where the menu is located
+'''	Returns:
+'''		True when successful
+'''	Examples:
+'''		oDoc.RemoveMenu("File")
+'''			' ...
+
+Dim bRemove As Boolean			'	Return value
+Dim oLayout As Object			'	com.sun.star.comp.framework.LayoutManager
+Dim oMenuBar As Object			'	com.sun.star.awt.XMenuBar or stardiv.Toolkit.VCLXMenuBar
+Dim sName As String				'	Menu name
+Dim iMenuId As Integer			'	Menu identifier
+Dim iMenuPosition As Integer	'	Menu position >= 0
+Dim i As Integer
+Const cstTilde = "~"
+
+Const cstThisSub = "SFDocuments.Document.RemoveMenu"
+Const cstSubArgs = "MenuHeader"
+
+	If ScriptForge.SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
+	bRemove = False
+
+Check:
+	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(MenuHeader, "MenuHeader", V_STRING) Then GoTo Finally
+	End If
+
+Try:
+	Set oLayout = _Document.CurrentController.Frame.LayoutManager
+	Set oMenuBar = oLayout.getElement("private:resource/menubar/menubar").XMenuBar
+
+	'	Search the menu identifier to remove by its name, Mark its position
+	With oMenuBar
+		iMenuPosition = -1
+		For i = 0 To .ItemCount - 1
+			iMenuId = .getItemId(i)
+			sName = Replace(.getItemText(iMenuId), cstTilde, "")
+			If MenuHeader= sName Then
+				iMenuPosition = i
+				Exit For
+			End If
+		Next i
+		'	Remove the found menu item
+		If iMenuPosition >= 0 Then
+			.removeItem(iMenuPosition, 1)
+			bRemove = True
+		End If
+	End With
+
+Finally:
+	RemoveMenu = bRemove
+	ScriptForge.SF_Utils._ExitFunction(cstThisSub)
+	Exit Function
+Catch:
+	GoTo Finally
+End Function   '   SFDocuments.SF_Document.RemoveMenu
+
+REM -----------------------------------------------------------------------------
 Public Sub RunCommand(Optional ByVal Command As Variant)
 ''' Run on the document the given menu command. The command is executed without arguments
 '''	A few typical commands:
@@ -811,7 +937,7 @@ Check:
 	If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
 		If Not _IsStillAlive() Then GoTo Finally
 		If Not SF_Utils._ValidateFile(FileName, "FileName") Then GoTo Finally
-		If Not SF_Utils._Validate(Overwrite, "Overwrite", V_BOOLEAN) Then GoTo Finally
+		If Not SF_Utils._Validate(Overwrite, "Overwrite", ScriptForge.V_BOOLEAN) Then GoTo Finally
 		If Not SF_Utils._Validate(Password, "Password", V_STRING) Then GoTo Finally
 		If Not SF_Utils._Validate(FilterName, "FilterName", V_STRING) Then GoTo Finally
 		If Not SF_Utils._Validate(FilterOptions, "FilterOptions", V_STRING) Then GoTo Finally
@@ -910,7 +1036,7 @@ Check:
 	If ScriptForge.SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
 		If Not _IsStillAlive() Then GoTo Finally
 		If Not SF_Utils._ValidateFile(FileName, "FileName") Then GoTo Finally
-		If Not SF_Utils._Validate(Overwrite, "Overwrite", V_BOOLEAN) Then GoTo Finally
+		If Not SF_Utils._Validate(Overwrite, "Overwrite", ScriptForge.V_BOOLEAN) Then GoTo Finally
 		If Not SF_Utils._Validate(Password, "Password", V_STRING) Then GoTo Finally
 		If Not SF_Utils._Validate(FilterName, "FilterName", V_STRING) Then GoTo Finally
 		If Not SF_Utils._Validate(FilterOptions, "FilterOptions", V_STRING) Then GoTo Finally
diff --git a/wizards/source/sfdocuments/SF_Writer.xba b/wizards/source/sfdocuments/SF_Writer.xba
index 4acdd5c750f0..96ed289f92ff 100644
--- a/wizards/source/sfdocuments/SF_Writer.xba
+++ b/wizards/source/sfdocuments/SF_Writer.xba
@@ -219,9 +219,11 @@ Public Function Methods() As Variant
 	Methods = Array( _
 					"Activate" _
 					, "CloseDocument" _
+					, "CreateMenu" _
 					, "ExportAsPDF" _
 					, "Forms" _
 					, "PrintOut" _
+					, "RemoveMenu" _
 					, "RunCommand" _
 					, "Save" _
 					, "SaveAs" _
@@ -493,6 +495,14 @@ Public Function CloseDocument(Optional ByVal SaveAsk As Variant) As Boolean
 End Function   '   SFDocuments.SF_Writer.CloseDocument
 
 REM -----------------------------------------------------------------------------
+Public Function CreateMenu(Optional ByVal MenuHeader As Variant _
+								, Optional ByVal Before As Variant _
+								, Optional ByVal SubmenuChar As Variant _
+								) As Object
+	Set CreateMenu = [_Super].CreateMenu(MenuHeader, Before, SubmenuChar)
+End Function	'	SFDocuments.SF_Writer.CreateMenu
+
+REM -----------------------------------------------------------------------------
 Public Function ExportAsPDF(Optional ByVal FileName As Variant _
 							, Optional ByVal Overwrite As Variant _
 							, Optional ByVal Pages As Variant _
@@ -503,6 +513,11 @@ Public Function ExportAsPDF(Optional ByVal FileName As Variant _
 End Function   '   SFDocuments.SF_Writer.ExportAsPDF
 
 REM -----------------------------------------------------------------------------
+Public Function RemoveMenu(Optional ByVal MenuHeader As Variant) As Boolean
+	RemoveMenu = [_Super].RemoveMenu(MenuHeader)
+End Function	'	SFDocuments.SF_Writer.RemoveMenu
+
+REM -----------------------------------------------------------------------------
 Public Sub RunCommand(Optional ByVal Command As Variant)
 	[_Super].RunCommand(Command)
 End Sub		  '   SFDocuments.SF_Writer.RunCommand