From 751a65e5be60a35ae970b3a66b2038d90ea580e4 Mon Sep 17 00:00:00 2001 From: Rafael Lima Date: Sun, 26 Nov 2023 17:02:19 +0100 Subject: Document SF Toolbar and ToolbarButton services Change-Id: I57df3b88660198d2432ff73ef1b37025e1b893a3 Reviewed-on: https://gerrit.libreoffice.org/c/help/+/159902 Tested-by: Jenkins Reviewed-by: Jean-Pierre Ledure Reviewed-by: Rafael Lima --- source/text/sbasic/shared/03/lib_ScriptForge.xhp | 14 +- source/text/sbasic/shared/03/sf_toc.xhp | 69 +++++ source/text/sbasic/shared/03/sf_toolbar.xhp | 261 ++++++++++++++++ source/text/sbasic/shared/03/sf_toolbarbutton.xhp | 345 ++++++++++++++++++++++ 4 files changed, 686 insertions(+), 3 deletions(-) create mode 100644 source/text/sbasic/shared/03/sf_toolbar.xhp create mode 100644 source/text/sbasic/shared/03/sf_toolbarbutton.xhp (limited to 'source/text') diff --git a/source/text/sbasic/shared/03/lib_ScriptForge.xhp b/source/text/sbasic/shared/03/lib_ScriptForge.xhp index af306b184a..7b978e89a5 100644 --- a/source/text/sbasic/shared/03/lib_ScriptForge.xhp +++ b/source/text/sbasic/shared/03/lib_ScriptForge.xhp @@ -123,13 +123,15 @@ FormControl
- Menu

+ Menu
+ PopupMenu
 - PopupMenu
- UI

+ Toolbar
+ ToolbarButton
+ UI
 @@ -237,6 +239,12 @@
+
+ +
+
+ +
diff --git a/source/text/sbasic/shared/03/sf_toc.xhp b/source/text/sbasic/shared/03/sf_toc.xhp index 849cb5829e..8255b37e30 100644 --- a/source/text/sbasic/shared/03/sf_toc.xhp +++ b/source/text/sbasic/shared/03/sf_toc.xhp @@ -925,6 +925,75 @@ +

ScriptForge.Toolbar service

+ +
+ + + + List of Properties in the Toolbar Service + + + + + + BuiltIn
+ Docked
+ HasGlobalScope
+ + + + + Name
+ ResourceURL

+ + + + + Visible
+ XUIElement

+ + + +
+
+ +

ScriptForge.ToolbarButton service

+ +
+ + + + List of Properties in the ToolbarButton Service + + + + + + Caption
+ Height
+ Index
+ OnClick
+ + + + + Parent
+ TipText
+ Visible

+ + + + + Width
+ X
+ Y

+ + + +
+
+

ScriptForge.UI service

diff --git a/source/text/sbasic/shared/03/sf_toolbar.xhp b/source/text/sbasic/shared/03/sf_toolbar.xhp new file mode 100644 index 0000000000..a5e19d6707 --- /dev/null +++ b/source/text/sbasic/shared/03/sf_toolbar.xhp @@ -0,0 +1,261 @@ + + + + + + + SFWidgets.Toolbar service + /text/sbasic/shared/03/sf_toolbar.xhp + + + + +
+ + Toolbar service + +
+ +
+

SFWidgets.Toolbar service

+ The Toolbar service allows to retrieve information related to the toolbars available for a specific document window. With this service it is possible to: + + + Toggle the visibility of specific toolbars. + + + Access information about the buttons available in each toolbar. + + +
+ Each %PRODUCTNAME application has its own set of available toolbars. This service handles both built-in and custom toolbars. + The status bar and the menu bar are not considered toolbars in the context of this service. + +

Service invocation

+ Before using the Toolbar service the ScriptForge library needs to be loaded or imported: + + + The Toolbar service is invoked using the Toolbars method, which is available in the following services: Calc, Datasheet, Document, FormDocument and Writer. + + The example below gets an Array with the names of the toolbars available in the current document. + + oDoc = CreateScriptService("Document", ThisComponent) + arrToolbars = oDoc.Toolbars() + MsgBox SF_String.Represent(arrToolbars) + + Use the Toolbars method without arguments to retrieve an array with available toolbar names. + The example below toggles the visibility of the Standard toolbar: + + oDoc = CreateScriptService("Document", ThisComponent) + toolbar = oDoc.Toolbars("standardbar") + toolbar.Visible = Not toolbar.Visible + + + + + bas = CreateScriptService("Basic") + doc = CreateScriptService("Document", bas.ThisComponent) + arr_toolbars = doc.Toolbars() + bas.MsgBox(repr(toolbars)) + + + bas = CreateScriptService("Basic") + doc = CreateScriptService("Document", bas.ThisComponent) + toolbar = doc.Toolbars("standardbar") + toolbar.Visible = not toolbar.Visible + + + + Toolbar service;BuiltIn property + Toolbar service;Docked property + Toolbar service;HasGlobalScope property + Toolbar service;Name property + Toolbar service;ResourceURL property + Toolbar service;Visible property + Toolbar service;XUIElement property + +

Properties

+
+ + + + Name + + + Readonly + + + Type + + + Description + + + + + BuiltIn + + + Yes + + + Boolean + + + Returns True when the toolbar is part of the set of standard toolbars shipped with %PRODUCTNAME. + + + + + Docked + + + Yes + + + Boolean + + + Returns True when the toolbar is active in the window and docked. + + + + + HasGlobalScope + + + Yes + + + Boolean + + + Returns True when the toolbar is available in all documents of the same type. + + + + + Name + + + Yes + + + String + + + Returns the name of the toolbar. + + + + + ResourceURL + + + Yes + + + String + + + Returns the resource URL of the toolbar, in the form private:toolbar/toolbar_name. + + + + + Visible + + + No + + + Boolean + + + Returns True when the toolbar is active and visible in the document window. + + + + + XUIElement + + + Yes + + + UNO Object + + + Returns the com.sun.star.ui.XUIElement UNO object that represents the toolbar. + + +
+
+ +
+ + + List of Methods in the Toolbar Service + + + + + ToolbarButtons
+ + + + + + + + + + + +
+
+ +
+ ToolbarButtons ------------------------------------------------------------------------------------- + + Toolbar service;ToolbarButtons + +

ToolbarButtons

+ Returns an Array containing the names of all toolbar buttons when called without arguments. + Provide the name of a toolbar button as argument to obtain a ToolbarButton service instance. + + + svc.ToolbarButtons(opt buttonname: str): any + + + buttonname: The name of a toolbar button in the current toolbar. + + The example below returns the command executed when the button New is clicked in the Standard toolbar: + + + oToolbar = oDoc.Toolbars("standardbar") + oToolbarButton = oToolbar.ToolbarButtons("New") + MsgBox oToolbarButton.OnClick + + + + toolbar = doc.Toolbars("standardbar") + toolbar_button = toolbar.ToolbarButtons("New") + bas.MsgBox(toolbar_button.OnClick) + + Inactive toolbars do not have buttons. Therefore, calling the ToolbarButtons method will make the toolbar visible. +
+ + +
+ +
+ + diff --git a/source/text/sbasic/shared/03/sf_toolbarbutton.xhp b/source/text/sbasic/shared/03/sf_toolbarbutton.xhp new file mode 100644 index 0000000000..e43c0147cd --- /dev/null +++ b/source/text/sbasic/shared/03/sf_toolbarbutton.xhp @@ -0,0 +1,345 @@ + + + + + + + SFWidgets.ToolbarButton service + /text/sbasic/shared/03/sf_toolbarbutton.xhp + + + + +
+ + ToolbarButton service + +
+ +
+

SFWidgets.ToolbarButton service

+ The ToolbarButton service allows to retrieve information related to the toolbar buttons available in a given toolbar. With this service it is possible to: + + + Toggle the visibility of toolbar elements. + + + Execute the command associated with a given toolbar button. + + +
+ +

Service invocation

+ Before using the ToolbarButton service the ScriptForge library needs to be loaded or imported: + + + The ToolbarButton service is invoked using the ToolbarButtons method from the Toolbar service. + + + The example below retrieves the names of all buttons available in the Standard toolbar. + + oDoc = CreateScriptService("Document", ThisComponent) + oToolbar = oDoc.Toolbars("standardbar") + arrToolbarButtons = oToolbar.ToolbarButtons() + MsgBox SF_String.Represent(arrToolbarButtons) + + Use the ToolbarButtons method without arguments to retrieve an array with all available toolbar button names. + The example below toggles the visibility of the Print button in the Standard toolbar: + + oDoc = CreateScriptService("Document", ThisComponent) + oToolbar = oDoc.Toolbars("standardbar") + oToolbarButton = oToolbar.ToolbarButtons("Print") + oToolbarButton.Visible = Not oToolbarButton.Visible + + The button name passed as argument to the ToolbarButtons method is the localized button name defined in the Tools - Customize - Toolbars dialog. + Inactive toolbars do not have buttons. Therefore, calling the ToolbarButtons method will make the toolbar visible. + + + + bas = CreateScriptService("Basic") + doc = CreateScriptService("Document", bas.ThisComponent) + toolbar = doc.Toolbars("standardbar") + arr_toolbar_buttons = toolbar.ToolbarButtons() + bas.MsgBox(repr(arr_toolbar_buttons)) + + + bas = CreateScriptService("Basic") + doc = CreateScriptService("Document", bas.ThisComponent) + toolbar = doc.Toolbars("standardbar") + toolbar_button = toolbar.ToolbarButtons("Print") + toolbar_button.Visible = not toolbar_button.Visible + + + + ToolbarButton service;Caption property + ToolbarButton service;Height property + ToolbarButton service;Index property + ToolbarButton service;OnClick property + ToolbarButton service;Parent property + ToolbarButton service;TipText property + ToolbarButton service;Visible property + ToolbarButton service;Width property + ToolbarButton service;X property + ToolbarButton service;Y property + +

Properties

+
+ + + + Name + + + Readonly + + + Type + + + Description + + + + + Caption + + + Yes + + + String + + + Returns the name of the button. + + + + + Height + + + Yes + + + Long + + + Returns the height of the button, in pixels. + + + + + Index + + + Yes + + + Long + + + Returns the index of the button in its parent toolbar. + + + + + OnClick + + + No + + + String + + + The UNO command or script executed when the button is pressed. Read the Wiki page Scripting Framework URI Specification to learn more on how to define a URI string. + + + + + Parent + + + Yes + + + Toolbar service + + + Returns a Toolbar service instance corresponding to the parent toolbar of the current toolbar button. + + + + + TipText + + + No + + + String + + + Specifies the tooltip text shown when the user hovers over the toolbar button. + + + + + Visible + + + No + + + Boolean + + + Specifies whether the toolbar button is visible or not. + + + + + Width + + + Yes + + + Long + + + Returns the width of the button, in pixels. + + + + + X + + + Yes + + + Long + + + Returns the X (horizontal) coordinate of the top-left corner of the button, in pixels. + + + + + Y + + + Yes + + + Long + + + Returns the Y (vertical) coordinate of the top-left corner of the button, in pixels. + + +
+
+ +

Use of ToolbarButton alongside the PopupMenu service

+ A common use case of the properties X and Y described above is to open a popup menu in the position where the toolbar button is located. + Suppose you create the script below and associate it with a button named "My Button" in the standardbar. When it is clicked, a popup menu will be shown with 3 options for the user to select. + + + Sub OpenPopupMenu() + GlobalScope.BasicLibraries.LoadLibrary("ScriptForge") + oDoc = CreateScriptService("Document", ThisComponent) + oToolbar = oDoc.Toolbars("standardbar") + oButton = oToolbar.ToolbarButtons("My Button") + oPopup = CreateScriptService("SFWidgets.PopupMenu", , oButton.X, oButton.Y + oButton.Height) + oPopup.AddItem("Item A", "A") + oPopup.AddItem("Item B", "B") + oPopup.AddItem("Item C", "C") + strResponse = oPopup.Execute(False) + MsgBox "Your choice: " & strResponse + End Sub + + + + def open_popup_menu(args=None): + bas = CreateScriptService("Basic") + doc = CreateScriptService("Document", bas.ThisComponent) + toolbar = doc.Toolbars("standardbar") + toolbutton = toolbar.ToolbarButtons("My Button") + popup = CreateScriptService("PopupMenu", None, toolbutton.X, toolbutton.Y + toolbutton.Height) + popup.AddItem("Item A", "A") + popup.AddItem("Item B", "B") + popup.AddItem("Item C", "C") + response = popup.Execute(False) + bas.MsgBox(f"Your choice: {response}") + + +
+ + + List of Methods in the ToolbarButton Service + + + + + Execute
+ + + + + + + + + + + +
+
+ +
+ Execute -------------------------------------------------------------------------------------------- + + ToolbarButton service;Execute + +

Execute

+ Executes the command or script associated with the toolbar button. + This method returns the value returned by the command or script executed. + Use the OnClick property to determine the command or script that shall be executed. If the command/script does not return any value, then Null is returned. + + + svc.Execute(): any + + + The example below executes the Print button from the Standard toolbar: + + + oDoc = CreateScriptService("Document", ThisComponent) + oToolbar = oDoc.Toolbars("standardbar") + oToolbarButton = oToolbar.ToolbarButtons("Print") + oToolbarButton.Execute() + + + + bas = CreateScriptService("Basic") + doc = CreateScriptService("Document", bas.ThisComponent) + toolbar = doc.Toolbars("standardbar") + toolbar_button = toolbar.ToolbarButtons("Print") + toolbar_button.Execute() + +
+ + +
+ +
+ + -- cgit