tdf#143585 Improve example on calling Calc functions in macros
Originally the example shown in "calc_functions.xhp" was embbeded from "03131600.xhp". So in this patch I created a brand new example in "03131600.xhp" and improved the example in "calc_functions.xhp".
Change-Id: I758a0e5dec3e66f924415970711dfa9044396026
Reviewed-on: https://gerrit.libreoffice.org/c/help/+/121060
Tested-by: Jenkins
Reviewed-by: Olivier Hallot <olivier.hallot@libreoffice.org>
diff --git a/source/text/sbasic/shared/03131600.xhp b/source/text/sbasic/shared/03131600.xhp
index 68b7df1..7342c9c 100644
--- a/source/text/sbasic/shared/03131600.xhp
+++ b/source/text/sbasic/shared/03131600.xhp
@@ -24,40 +24,35 @@
</topic>
</meta>
<body>
<section id="createunoservice">
<bookmark xml-lang="en-US" branch="index" id="bm_id3150682">
<bookmark_value>CreateUnoService function</bookmark_value>
<bookmark_value>API;FilePicker</bookmark_value>
<bookmark_value>API;FunctionAccess</bookmark_value>
</bookmark>
<h1 id="hd_id3150682"><variable id="createunoserviceh1"><link href="text/sbasic/shared/03131600.xhp" name="CreateUnoService Function">CreateUnoService Function</link></variable></h1>
<paragraph id="par_id3152924" role="paragraph" xml-lang="en-US">Instantiates a Uno service with the ProcessServiceManager.</paragraph>
</section>
<embed href="text/sbasic/shared/00000003.xhp#functsyntax"/>
<paragraph id="par_id3153346" role="code" xml-lang="en-US">oService = CreateUnoService( Uno service name )</paragraph>
<paragraph id="par_idN1060F" role="paragraph" xml-lang="en-US">For a list of available services, go to: <link href="https://api.libreoffice.org/docs/idl/ref/namespacecom_1_1sun_1_1star.html" name="api.libreoffice.org com::sun::star Module Reference">https://api.libreoffice.org/docs/idl/ref/namespacecom_1_1sun_1_1star.html</link></paragraph>
<section id="createunoservice">
<bookmark xml-lang="en-US" branch="index" id="bm_id3150682">
<bookmark_value>CreateUnoService function</bookmark_value>
<bookmark_value>API;FilePicker</bookmark_value>
<bookmark_value>API;SimpleFileAccess</bookmark_value>
</bookmark>
<h1 id="hd_id3150682"><variable id="createunoserviceh1"><link href="text/sbasic/shared/03131600.xhp" name="CreateUnoService Function">CreateUnoService Function</link></variable></h1>
<paragraph id="par_id3152924" role="paragraph" xml-lang="en-US">Instantiates a Uno service with the <literal>ProcessServiceManager</literal>.</paragraph>
</section>
<embed href="text/sbasic/shared/00000003.xhp#functsyntax"/>
<paragraph role="paragraph" id="par_id511629989178074"><input>oService = CreateUnoService( UNO service name )</input></paragraph>
<tip id="par_id921629989537850">For a list of available services, visit the <link href="https://api.libreoffice.org/docs/idl/ref/namespacecom_1_1sun_1_1star.html" name="UNO_Service_Names">com::sun::star Module</link> reference page.</tip>
<embed href="text/sbasic/shared/00000003.xhp#functexample"/>
<paragraph role="paragraph" id="par_id891561653344669">The example below creates the function <literal>FileExists</literal> that uses the service <literal>com.sun.star.ucb.SimpleFileAccess</literal> to test if a given path is an existing file.</paragraph>
<bascode>
<paragraph role="bascode" id="bas_id901629989240801">Function FileExists(sPath as String) as Boolean</paragraph>
<paragraph role="bascode" id="bas_id361629989241073"> Dim svcSFA as Object</paragraph>
<paragraph role="bascode" id="bas_id461629989241289"> Set svcSFA = CreateUnoService("com.sun.star.ucb.SimpleFileAccess")</paragraph>
<paragraph role="bascode" id="bas_id441629989241521"> Dim bExists as Boolean : bExists = svcSFA.exists(sPath)</paragraph>
<paragraph role="bascode" id="bas_id651629989241801"> Dim bIsFolder as Boolean : bIsFolder = svcSFA.IsFolder(sPath)</paragraph>
<paragraph role="bascode" id="bas_id521629989242114"> FileExists = bExists And Not bIsFolder</paragraph>
<paragraph role="bascode" id="bas_id211629989242416">End Function</paragraph>
</bascode>
<tip id="par_id351629989310797">UNO services have an extensive online documentation in the <link href="https://api.libreoffice.org/" name="API_Website">api.libreoffice.org</link> website. Visit the <link href="https://api.libreoffice.org/docs/idl/ref/servicecom_1_1sun_1_1star_1_1ucb_1_1SimpleFileAccess.html" name="SimpleFileAccess_Page">SimpleFileAccess Service</link> reference page to learn more about the methods provided by the service used in the example above.</tip>
<embed href="text/sbasic/shared/00000003.xhp#functexample"/>
<bookmark xml-lang="en-US" branch="index" id="bm_id731561653332192">
<bookmark_value>Calc functions;API Service</bookmark_value>
</bookmark>
<paragraph role="paragraph" id="par_id891561653344669">Calling Calc functions in Basic:</paragraph>
<section id="calcinternalfunctions">
<bascode>
<paragraph role="bascode" id="par_id741592351349391" xml-lang="en-US">REM The code below does not work for add-in functions, which have a different calling procedure.</paragraph>
<paragraph role="bascode" id="par_id511561653511948" xml-lang="en-US" localize="false">Function MyVlook(item, InRange As Object, FromCol As Integer)</paragraph>
<paragraph role="bascode" id="par_id771561653522280" xml-lang="en-US" localize="false"> Dim oService As Object</paragraph>
<paragraph role="bascode" id="par_id791561653536896" xml-lang="en-US" localize="false"> oService = createUnoService("com.sun.star.sheet.FunctionAccess")</paragraph>
<paragraph role="bascode" id="par_id31561653863623" xml-lang="en-US"> REM Always use the function English name</paragraph>
<paragraph role="bascode" id="par_id391561653548274" xml-lang="en-US" localize="false"> MyVlook = oService.callFunction("VLOOKUP",Array(item, InRange, FromCol, True))</paragraph>
<paragraph role="bascode" id="par_id951561653556383" xml-lang="en-US" localize="false">End Function</paragraph>
</bascode>
</section>
<embed href="text/sbasic/shared/00000003.xhp#functexample"/>
<paragraph id="par_id3154046" role="paragraph" localize="false" xml-lang="en-US"><literal>oIntrospection = CreateUnoService( "com.sun.star.beans.Introspection" )</literal></paragraph>
<bookmark xml-lang="en-US" branch="index" id="bm_id8334604">
<bookmark_value>filepicker;API service</bookmark_value>
</bookmark>
<paragraph id="par_idN10625" role="paragraph" xml-lang="en-US">The following code uses a service to open a file open dialog:</paragraph>
<paragraph id="par_idN10625" role="paragraph" xml-lang="en-US">The following code uses the service <literal>com.sun.star.ui.dialogs.FilePicker</literal> to show a file open dialog:</paragraph>
<bascode>
<paragraph id="par_idm1206777616" role="bascode" localize="false" xml-lang="en-US">Sub Main</paragraph>
<paragraph id="par_idN1062B" role="bascode" xml-lang="en-US"> fName = FileOpenDialog ("Please select a file")</paragraph>
@@ -78,4 +73,4 @@
<embed href="text/sbasic/shared/calc_functions.xhp#CallingCalcFunctionsh1"/>
</section>
</body>
</helpdocument>
\ No newline at end of file
</helpdocument>
diff --git a/source/text/sbasic/shared/calc_functions.xhp b/source/text/sbasic/shared/calc_functions.xhp
index a58f14f..02fa02a 100644
--- a/source/text/sbasic/shared/calc_functions.xhp
+++ b/source/text/sbasic/shared/calc_functions.xhp
@@ -16,20 +16,45 @@
</topic>
</meta>
<body>
<bookmark xml-lang="en-US" branch="index" id="bm_id291592361063458">
<bookmark xml-lang="en-US" branch="index" id="bm_id291592361063458">
<bookmark_value>calling Calc function;macros</bookmark_value>
<bookmark_value>macros;calling Calc function</bookmark_value>
<bookmark_value>createUNOservice function;calling Calc function</bookmark_value>
<bookmark_value>API;addin.Analysis</bookmark_value>
</bookmark>
<h1 id="hd_id91592352089011"><variable id="CallingCalcFunctionsh1"><link href="text/sbasic/shared/calc_functions.xhp" name="Calling Calc Functions">Calling Calc Functions</link></variable></h1>
<paragraph role="paragraph" id="par_id1001592359117987">In addition to the native BASIC functions, you can call Calc functions in your macros and scripts.</paragraph>
<h2 id="hd_id251592352174921">Calling Internal Calc functions in Basic</h2>
</bookmark>
<h1 id="hd_id91592352089011"><variable id="CallingCalcFunctionsh1"><link href="text/sbasic/shared/calc_functions.xhp" name="Calling Calc Functions">Calling Calc Functions</link></variable></h1>
<paragraph role="paragraph" id="par_id1001592359117987">In addition to the native BASIC functions, you can call Calc functions in your macros and scripts.</paragraph>
<h2 id="hd_id251592352174921">Calling Internal Calc functions in Basic</h2>
<paragraph role="paragraph" id="par_id731592352332694">Use the <literal>CreateUNOService</literal> function to access the <literal>com.sun.star.sheet.FunctionAccess</literal> service.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functexample"/>
<embed href="text/sbasic/shared/03131600.xhp#calcinternalfunctions"/>
<h2 id="hd_id561592352225441">Calling Add-In Calc Functions in BASIC</h2>
<paragraph role="paragraph" id="par_id261592359338681">The Calc Add-In functions are in service <literal>com.sun.star.sheet.addin.Analysis</literal>.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functexample"/>
<paragraph role="paragraph" id="par_id751629987917982">The example below creates a function named <literal>MyVlook</literal> that calls the <literal>VLOOKUP</literal> Calc function over a data array passed as argument and returns the value found by the function.</paragraph>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id371629987889347">Function MyVlook(Lookup, DataArray As Object, Index As Integer, SortedRangeLookup as Byte)</paragraph>
<paragraph role="bascode" localize="false" id="bas_id21629987889617"> Dim oService As Object</paragraph>
<paragraph role="bascode" localize="false" id="bas_id671629987889986"> Set oService = createUnoService("com.sun.star.sheet.FunctionAccess")</paragraph>
<paragraph role="bascode" id="bas_id271629987890173"> ' Always use the function name in English</paragraph>
<paragraph role="bascode" localize="false" id="bas_id831629987890360"> MyVlook = oService.callFunction("VLOOKUP", Array(Lookup, DataArray, Index, SortedRangeLookup))</paragraph>
<paragraph role="bascode" localize="false" id="bas_id91629987891281">End Function</paragraph>
</bascode>
<paragraph role="paragraph" id="par_id241629988142878">The macro below presents an example of how the <literal>MyVlook</literal> function can be called. If first creates a 5-by-2 data array and then calls the function <literal>MyVlook</literal> and shows the returned value using <literal>MsgBox</literal>.</paragraph>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id221629988249322">Sub CallingMyVlook()</paragraph>
<paragraph role="bascode" id="bas_id331629988249519"> ' Creates a 5 by 2 array and fills it with data</paragraph>
<paragraph role="bascode" localize="false" id="bas_id281629988249703"> Dim myData(1 to 5, 1 to 2) as Variant</paragraph>
<paragraph role="bascode" id="bas_id641629988249903"> myData(1, 1) = 1 : myData(1, 2) = "Strongly disagree"</paragraph>
<paragraph role="bascode" id="bas_id201629988250130"> myData(2, 1) = 3 : myData(2, 2) = "Disagree"</paragraph>
<paragraph role="bascode" id="bas_id291629988250317"> myData(3, 1) = 5 : myData(3, 2) = "Undecided"</paragraph>
<paragraph role="bascode" id="bas_id731629988250530"> myData(4, 1) = 7 : myData(4, 2) = "Agree"</paragraph>
<paragraph role="bascode" id="bas_id641629988250759"> myData(5, 1) = 9 : myData(5, 2) = "Strongly agree"</paragraph>
<paragraph role="bascode" id="bas_id521629988250997"> ' Looks up the data array</paragraph>
<paragraph role="bascode" localize="false" id="bas_id401629988251210"> Dim result as String</paragraph>
<paragraph role="bascode" localize="false" id="bas_id331629988324037"> result = MyVlook(4, myData, 2, 1)</paragraph>
<paragraph role="bascode" id="bas_id491629988324413"> ' Shows the message "Disagree"</paragraph>
<paragraph role="bascode" localize="false" id="bas_id871629988324637"> MsgBox result</paragraph>
<paragraph role="bascode" localize="false" id="bas_id321629988324798">End Sub</paragraph>
</bascode>
<h2 id="hd_id561592352225441">Calling Add-In Calc Functions in BASIC</h2>
<paragraph role="paragraph" id="par_id261592359338681">The Calc Add-In functions are in service <literal>com.sun.star.sheet.addin.Analysis</literal>.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functexample"/>
<bascode>
<paragraph role="bascode" id="bas_id421592358343633">REM Example calling Addin function SQRTPI</paragraph>
@@ -39,7 +64,7 @@
<paragraph role="bascode" id="bas_id211592358377026"> MySQRTPI = oService.getSqrtPi(arg)</paragraph>
<paragraph role="bascode" id="bas_id451592358385346" localize="false">End Function</paragraph>
</bascode>
<paragraph role="paragraph" id="par_id651629988674793">The table below presents a list of all Calc Add-In functions and their respective UNO service names.</paragraph>
<table id="tab_id971592356505781">
<tablerow>
<tablecell>
@@ -294,7 +319,7 @@
<paragraph id="par_id221592355620084" role="tablecontent" xml-lang="en-US" >EFFECT</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id221592355620084" role="tablecontent" localize="false" >com.sun.star.sheet.addin.Analysis.getEffect</paragraph>
<paragraph id="par_id221592355620085" role="tablecontent" localize="false" >com.sun.star.sheet.addin.Analysis.getEffect</paragraph>
</tablecell>
</tablerow>
<tablerow>
@@ -454,7 +479,7 @@
<paragraph id="par_id51592355688940" role="tablecontent" xml-lang="en-US" >IMDIV</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id51592355688940" role="tablecontent" localize="false" >com.sun.star.sheet.addin.Analysis.getImdiv</paragraph>
<paragraph id="par_id51592355688941" role="tablecontent" localize="false" >com.sun.star.sheet.addin.Analysis.getImdiv</paragraph>
</tablecell>
</tablerow>
<tablerow>
