diff options
Diffstat (limited to 'helpcontent2/source/text/sbasic/shared/03/sf_toolbarbutton.xhp')
| -rw-r--r-- | helpcontent2/source/text/sbasic/shared/03/sf_toolbarbutton.xhp | 345 |
1 files changed, 345 insertions, 0 deletions
diff --git a/helpcontent2/source/text/sbasic/shared/03/sf_toolbarbutton.xhp b/helpcontent2/source/text/sbasic/shared/03/sf_toolbarbutton.xhp new file mode 100644 index 0000000000..e43c0147cd --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/sf_toolbarbutton.xhp @@ -0,0 +1,345 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> +<!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * +--> + +<meta> + <topic id="SF_ToolbarButton" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">SFWidgets.ToolbarButton service</title> + <filename>/text/sbasic/shared/03/sf_toolbarbutton.xhp</filename> + </topic> +</meta> + +<body> + <section id="SFWidgets-sf_toolbarbutton"> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id261582733781987"> + <bookmark_value>ToolbarButton service</bookmark_value> + </bookmark> + </section> + + <section id="abstract"> + <h1 id="hd_id731582733781114"><variable id="ToolbarButtonService"><link href="text/sbasic/shared/03/sf_toolbarbutton.xhp"><literal>SFWidgets</literal>.<literal>ToolbarButton</literal> service</link></variable></h1> + <paragraph role="paragraph" id="par_id571700837631557">The <literal>ToolbarButton</literal> service allows to retrieve information related to the toolbar buttons available in a given toolbar. With this service it is possible to:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id891589189452545" role="listitem">Toggle the visibility of toolbar elements.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id811589189463041" role="listitem">Execute the command associated with a given toolbar button.</paragraph> + </listitem> + </list> + </section> + + <h2 id="hd_id581582885621841" xml-lang="en-US">Service invocation</h2> + <paragraph role="paragraph" id="par_id141609955500101">Before using the <literal>ToolbarButton</literal> service the <literal>ScriptForge</literal> library needs to be loaded or imported:</paragraph> + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#importLibs"/> + + <paragraph role="paragraph" id="par_id411700851985942">The <literal>ToolbarButton</literal> service is invoked using the <literal>ToolbarButtons</literal> method from the <literal>Toolbar</literal> service.</paragraph> + + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <paragraph role="paragraph" id="par_id771700853155061">The example below retrieves the names of all buttons available in the <menuitem>Standard</menuitem> toolbar.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id561700853223079">oDoc = CreateScriptService("Document", ThisComponent)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id821700853223579">oToolbar = oDoc.Toolbars("standardbar")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id201701020721930">arrToolbarButtons = oToolbar.ToolbarButtons()</paragraph> + <paragraph role="bascode" localize="false" id="bas_id751700853223764">MsgBox SF_String.Represent(arrToolbarButtons)</paragraph> + </bascode> + <tip id="par_id961700853354817">Use the <literal>ToolbarButtons</literal> method without arguments to retrieve an array with all available toolbar button names.</tip> + <paragraph role="paragraph" id="par_id171700853415555">The example below toggles the visibility of the <menuitem>Print</menuitem> button in the <menuitem>Standard</menuitem> toolbar:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id141700853757638">oDoc = CreateScriptService("Document", ThisComponent)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id651700853757894">oToolbar = oDoc.Toolbars("standardbar")</paragraph> + <paragraph role="bascode" id="bas_id117008537580631">oToolbarButton = oToolbar.ToolbarButtons("Print")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id161701021081876">oToolbarButton.Visible = Not oToolbarButton.Visible</paragraph> + </bascode> + <tip id="par_id981701021131646">The button name passed as argument to the <literal>ToolbarButtons</literal> method is the localized button name defined in the <menuitem>Tools - Customize - Toolbars</menuitem> dialog.</tip> + <note id="par_id531701012694220">Inactive toolbars do not have buttons. Therefore, calling the <literal>ToolbarButtons</literal> method will make the toolbar visible.</note> + + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id171701008968310">bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id621701008969941">doc = CreateScriptService("Document", bas.ThisComponent)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id441701008970173">toolbar = doc.Toolbars("standardbar")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id891701021459391">arr_toolbar_buttons = toolbar.ToolbarButtons()</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id617010091805031">bas.MsgBox(repr(arr_toolbar_buttons))</paragraph> + </pycode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id221701009213403">bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id481701009213644">doc = CreateScriptService("Document", bas.ThisComponent)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id801701009213818">toolbar = doc.Toolbars("standardbar")</paragraph> + <paragraph role="pycode" id="pyc_id351701021554314">toolbar_button = toolbar.ToolbarButtons("Print")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id381701009320054">toolbar_button.Visible = not toolbar_button.Visible</paragraph> + </pycode> + + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id81611339709014"> + <bookmark_value>ToolbarButton service;Caption property</bookmark_value> + <bookmark_value>ToolbarButton service;Height property</bookmark_value> + <bookmark_value>ToolbarButton service;Index property</bookmark_value> + <bookmark_value>ToolbarButton service;OnClick property</bookmark_value> + <bookmark_value>ToolbarButton service;Parent property</bookmark_value> + <bookmark_value>ToolbarButton service;TipText property</bookmark_value> + <bookmark_value>ToolbarButton service;Visible property</bookmark_value> + <bookmark_value>ToolbarButton service;Width property</bookmark_value> + <bookmark_value>ToolbarButton service;X property</bookmark_value> + <bookmark_value>ToolbarButton service;Y property</bookmark_value> + </bookmark> + <h2 id="hd_id351582885195476" xml-lang="en-US">Properties</h2> + <section id="properties_toc"> + <table id="tab_id971582885195582"> + <tablerow> + <tablecell> + <paragraph id="par_id41582885195836" role="tablehead">Name</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id31582885195372" role="tablehead">Readonly</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id31582885195238" role="tablehead">Type</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id931582885195131" role="tablehead">Description</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id7715828856553" role="tablecontent" localize="false">Caption</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id861582885655779" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id271582885655525" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id581582885655885" role="tablecontent">Returns the name of the button.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id771582885655313" role="tablecontent" localize="false">Height</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id861582885655669" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id271582885623525" role="tablecontent" localize="false">Long</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id581582885657885" role="tablecontent">Returns the height of the button, in pixels.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id771582885655394" role="tablecontent" localize="false">Index</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id861582885655710" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id271582885651142" role="tablecontent" localize="false">Long</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id581582885655102" role="tablecontent">Returns the index of the button in its parent toolbar.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id771582885655332" role="tablecontent" localize="false">OnClick</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id861582885655205" role="tablecontent">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id271582885655787" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id581582885655369" role="tablecontent">The UNO command or script executed when the button is pressed. Read the Wiki page <link href="https://wiki.documentfoundation.org/Documentation/DevGuide/Scripting_Framework#Scripting_Framework_URI_Specification">Scripting Framework URI Specification</link> to learn more on how to define a URI string.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id771582885655349" role="tablecontent" localize="false">Parent</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id861582885655966" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id271582885605065" role="tablecontent"><literal>Toolbar</literal> service</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id581582885655812" role="tablecontent">Returns a <literal>Toolbar</literal> service instance corresponding to the parent toolbar of the current toolbar button.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id771582885655387" role="tablecontent" localize="false">TipText</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id861582885655212" role="tablecontent">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id271582885655373" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id581582885655344" role="tablecontent">Specifies the tooltip text shown when the user hovers over the toolbar button.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id771582885655311" role="tablecontent" localize="false">Visible</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id861582885655788" role="tablecontent">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id271582885655522" role="tablecontent" localize="false">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id581582885655062" role="tablecontent">Specifies whether the toolbar button is visible or not.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id771582885652661" role="tablecontent" localize="false">Width</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id861582885651058" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id271582885659542" role="tablecontent" localize="false">Long</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id581582885653342" role="tablecontent">Returns the width of the button, in pixels.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id771582885604761" role="tablecontent" localize="false">X</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id861582885636258" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id271582885699442" role="tablecontent" localize="false">Long</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id581582885641742" role="tablecontent">Returns the X (horizontal) coordinate of the top-left corner of the button, in pixels.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id771582885604161" role="tablecontent" localize="false">Y</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id861582885603158" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id271582885603642" role="tablecontent" localize="false">Long</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id581582885609942" role="tablecontent">Returns the Y (vertical) coordinate of the top-left corner of the button, in pixels.</paragraph> + </tablecell> + </tablerow> + </table> + </section> + + <h2 id="hd_id501701094012462">Use of <literal>ToolbarButton</literal> alongside the <literal>PopupMenu</literal> service</h2> + <paragraph role="paragraph" id="par_id731701094077095">A common use case of the properties <literal>X</literal> and <literal>Y</literal> described above is to open a popup menu in the position where the toolbar button is located.</paragraph> + <paragraph role="paragraph" id="par_id761701094138529">Suppose you create the script below and associate it with a button named "My Button" in the <literal>standardbar</literal>. When it is clicked, a popup menu will be shown with 3 options for the user to select.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id871701094239003">Sub OpenPopupMenu()</paragraph> + <paragraph role="bascode" localize="false" id="bas_id991701094239228"> GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id100170109439419"> oDoc = CreateScriptService("Document", ThisComponent)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id811701094239628"> oToolbar = oDoc.Toolbars("standardbar")</paragraph> + <paragraph role="bascode" id="bas_id971701094239852"> oButton = oToolbar.ToolbarButtons("My Button")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id741701094240084"> oPopup = CreateScriptService("SFWidgets.PopupMenu", , oButton.X, oButton.Y + oButton.Height)</paragraph> + <paragraph role="bascode" id="bas_id521701094240308"> oPopup.AddItem("Item A", "A")</paragraph> + <paragraph role="bascode" id="bas_id201701094240523"> oPopup.AddItem("Item B", "B")</paragraph> + <paragraph role="bascode" id="bas_id961701094240764"> oPopup.AddItem("Item C", "C")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id381701094240979"> strResponse = oPopup.Execute(False)</paragraph> + <paragraph role="bascode" id="bas_id531701094241275"> MsgBox "Your choice: " & strResponse</paragraph> + <paragraph role="bascode" localize="false" id="bas_id481701094241629">End Sub</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id651701094979197">def open_popup_menu(args=None):</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id481701094979605"> bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id921701094979429"> doc = CreateScriptService("Document", bas.ThisComponent)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id471701094979804"> toolbar = doc.Toolbars("standardbar")</paragraph> + <paragraph role="pycode" id="pyc_id231701094980046"> toolbutton = toolbar.ToolbarButtons("My Button")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id921701094980261"> popup = CreateScriptService("PopupMenu", None, toolbutton.X, toolbutton.Y + toolbutton.Height)</paragraph> + <paragraph role="pycode" id="pyc_id521701094980469"> popup.AddItem("Item A", "A")</paragraph> + <paragraph role="pycode" id="pyc_id841701094980684"> popup.AddItem("Item B", "B")</paragraph> + <paragraph role="pycode" id="pyc_id441701094980908"> popup.AddItem("Item C", "C")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id501701094981133"> response = popup.Execute(False)</paragraph> + <paragraph role="pycode" id="pyc_id241701094981357"> bas.MsgBox(f"Your choice: {response}")</paragraph> + </pycode> + + <section id="methods_toc"> + <table id="tab_id901611086279902"> + <tablerow> + <tablecell colspan="3"><paragraph id="par_id651606319520519" role="tablehead">List of Methods in the ToolbarButton Service</paragraph></tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id761611086279902" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_toolbarbutton.xhp#Execute">Execute</link><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id141611086279902" role="tablecontent" localize="false"> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id761611086279903" role="tablecontent" localize="false"> + </paragraph> + </tablecell> + </tablerow> + </table> + </section> + + <section id="Execute"> + <comment> Execute -------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919969883"> + <bookmark_value>ToolbarButton service;Execute</bookmark_value> + </bookmark> + <h2 id="hd_id201589199698251" localize="false">Execute</h2> + <paragraph role="paragraph" id="par_id93158919969864">Executes the command or script associated with the toolbar button.</paragraph> + <paragraph role="paragraph" id="par_id191701023292148">This method returns the value returned by the command or script executed.</paragraph> + <tip id="par_id731701023160247">Use the <literal>OnClick</literal> property to determine the command or script that shall be executed. If the command/script does not return any value, then <literal>Null</literal> is returned.</tip> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id181622827609276"> + <input>svc.Execute(): any</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id601611148017930">The example below executes the <menuitem>Print</menuitem> button from the <menuitem>Standard</menuitem> toolbar:</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id421701012864607">oDoc = CreateScriptService("Document", ThisComponent)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id771701013457279">oToolbar = oDoc.Toolbars("standardbar")</paragraph> + <paragraph role="bascode" id="bas_id841701013457456">oToolbarButton = oToolbar.ToolbarButtons("Print")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id661701023616206">oToolbarButton.Execute()</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id221701002583403">bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id481701009203644">doc = CreateScriptService("Document", bas.ThisComponent)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id801701009244418">toolbar = doc.Toolbars("standardbar")</paragraph> + <paragraph role="pycode" id="pyc_id351701020654314">toolbar_button = toolbar.ToolbarButtons("Print")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id381701009352154">toolbar_button.Execute()</paragraph> + </pycode> + </section> + + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#SF_InternalUse"/> + <section id="relatedtopics"> + <embed href="text/sbasic/shared/03/sf_toolbar.xhp#ToolbarService"/> + </section> +</body> +</helpdocument> |