7vbG4‖SFWidgets.ToolbarButton service

3WPXi‖The ToolbarButton service allows to retrieve information related to the toolbar buttons available in a given toolbar. With this service it is possible to:

GF4Sh‖Service invocation

Jv5uU‖Before using the ToolbarButton service the ScriptForge library needs to be loaded or imported:

note

gF8D8‖• Basic macros require to load ScriptForge library using the following statement:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Python scripts require an import from scriptforge module:
from scriptforge import CreateScriptService


84iEK‖The ToolbarButton service is invoked using the ToolbarButtons method from the Toolbar service.

3aa4B‖In Basic

bXAc8‖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)
  
tip

dBPud‖Use the ToolbarButtons method without arguments to retrieve an array with all available toolbar button names.


MCeGq‖The example below toggles the visibility of the Print button in the Standard toolbar:


    oDoc = CreateScriptService("Document", ThisComponent)
    oToolbar = oDoc.Toolbars("standardbar")
    EccFb‖oToolbarButton = oToolbar.ToolbarButtons("Print")
    oToolbarButton.Visible = Not oToolbarButton.Visible
  
tip

WL7SE‖The button name passed as argument to the ToolbarButtons method is the localized button name defined in the Tools - Customize - Toolbars dialog.


note

UbFqB‖Inactive toolbars do not have buttons. Therefore, calling the ToolbarButtons method will make the toolbar visible.


BenDd‖In Python

    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")
    noSwD‖toolbar_button = toolbar.ToolbarButtons("Print")
    toolbar_button.Visible = not toolbar_button.Visible
  

zVUEe‖Properties

v9qLc‖Name

ZEAQj‖Readonly

XsFaH‖Type

L7CFQ‖Description

Caption

rD5Wn‖Yes

String

HmTft‖Returns the name of the button.

Height

XFmBe‖Yes

Long

wxbpS‖Returns the height of the button, in pixels.

Index

KKkBJ‖Yes

Long

DPmJW‖Returns the index of the button in its parent toolbar.

OnClick

NWZML‖No

String

DarcX‖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

5cZz5‖Yes

CVk4f‖Toolbar service

ky5Ft‖Returns a Toolbar service instance corresponding to the parent toolbar of the current toolbar button.

TipText

evEJD‖No

String

RFDDd‖Specifies the tooltip text shown when the user hovers over the toolbar button.

Visible

7rEk3‖No

Boolean

Xwj6X‖Specifies whether the toolbar button is visible or not.

Width

MAiCW‖Yes

Long

nBeFQ‖Returns the width of the button, in pixels.

X

XBYFY‖Yes

Long

4uB2C‖Returns the X (horizontal) coordinate of the top-left corner of the button, in pixels.

Y

nZBBC‖Yes

Long

sapte‖Returns the Y (vertical) coordinate of the top-left corner of the button, in pixels.


5EuPv‖Use of ToolbarButton alongside the PopupMenu service

BA5AH‖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.

y6sZ3‖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.

3aa4B‖In Basic

    Sub OpenPopupMenu()
        GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
        oDoc = CreateScriptService("Document", ThisComponent)
        oToolbar = oDoc.Toolbars("standardbar")
    dQW6G‖    oButton = oToolbar.ToolbarButtons("My Button")
        oPopup = CreateScriptService("SFWidgets.PopupMenu", , oButton.X, oButton.Y + oButton.Height)
    du4rs‖    oPopup.AddItem("Item A", "A")
    Z42ng‖    oPopup.AddItem("Item B", "B")
    vr533‖    oPopup.AddItem("Item C", "C")
        strResponse = oPopup.Execute(False)
    DkPqx‖    MsgBox "Your choice: " & strResponse
    End Sub
  
BenDd‖In Python

    def open_popup_menu(args=None):
        bas = CreateScriptService("Basic")
        doc = CreateScriptService("Document", bas.ThisComponent)
        toolbar = doc.Toolbars("standardbar")
    FBrD2‖    toolbutton = toolbar.ToolbarButtons("My Button")
        popup = CreateScriptService("PopupMenu", None, toolbutton.X, toolbutton.Y + toolbutton.Height)
    QvGxh‖    popup.AddItem("Item A", "A")
    EocEP‖    popup.AddItem("Item B", "B")
    DAFTZ‖    popup.AddItem("Item C", "C")
        response = popup.Execute(False)
    XR2zA‖    bas.MsgBox(f"Your choice: {response}")
  

FdzNA‖List of Methods in the ToolbarButton Service

Execute


Execute

oGWqY‖Executes the command or script associated with the toolbar button.

7BYZB‖This method returns the value returned by the command or script executed.

tip

DypG2‖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.


FVEx2‖Syntax:

svc.Execute(): any

EFSA4‖Example:

o3Jvt‖The example below executes the Print button from the Standard toolbar:

3aa4B‖In Basic

      oDoc = CreateScriptService("Document", ThisComponent)
      oToolbar = oDoc.Toolbars("standardbar")
      PErti‖oToolbarButton = oToolbar.ToolbarButtons("Print")
      oToolbarButton.Execute()
    
BenDd‖In Python

      bas = CreateScriptService("Basic")
    doc = CreateScriptService("Document", bas.ThisComponent)
    toolbar = doc.Toolbars("standardbar")
    izBv6‖toolbar_button = toolbar.ToolbarButtons("Print")
    toolbar_button.Execute()
    
warning

uzETY‖All ScriptForge Basic routines or identifiers that are prefixed with an underscore character "_" are reserved for internal use. They are not meant be used in Basic macros or Python scripts.