AllLangHelp_sbasic.mk | 1
source/auxiliary/sbasic.tree | 1
source/text/sbasic/python/python_2_basic.xhp | 151 +++++++++++++++++++
source/text/sbasic/python/python_document_events.xhp | 3
source/text/sbasic/python/python_examples.xhp | 1
source/text/sbasic/python/python_screen.xhp | 1
source/text/scalc/01/func_switch.xhp | 2
7 files changed, 158 insertions(+), 2 deletions(-)
New commits:
commit 3d1c81107309511f00a024a2e1a706a8bf96af47
Author: LibreOfficiant <libreoffici...@sfr.fr>
AuthorDate: Wed Jul 3 19:43:26 2019 +0200
Commit: Olivier Hallot <olivier.hal...@libreoffice.org>
CommitDate: Mon Jul 15 02:23:47 2019 +0200
Python to Basic Help page
- Python x Basic inter-language calls
- Dialog handlers with Basic or Python
Amend 1
- place page at right path
- inter-page link calls
- entry in Contents
- Some changes in passive voice, articles in text
Change-Id: I5bb54150f534486c092036a8ed4fa7cc38cc9ef0
Reviewed-on: https://gerrit.libreoffice.org/75057
Tested-by: Jenkins
Reviewed-by: Olivier Hallot <olivier.hal...@libreoffice.org>
diff --git a/AllLangHelp_sbasic.mk b/AllLangHelp_sbasic.mk
index a1f3fed2c..1cac18fe4 100644
--- a/AllLangHelp_sbasic.mk
+++ b/AllLangHelp_sbasic.mk
@@ -372,6 +372,7 @@ $(eval $(call gb_AllLangHelp_add_helpfiles,sbasic,\
helpcontent2/source/text/sbasic/shared/special_vba_func \
helpcontent2/source/text/sbasic/shared/vbasupport \
helpcontent2/source/text/sbasic/python/main0000 \
+ helpcontent2/source/text/sbasic/python/python_2_basic \
helpcontent2/source/text/sbasic/python/python_dialogs \
helpcontent2/source/text/sbasic/python/python_document_events \
helpcontent2/source/text/sbasic/python/python_examples \
diff --git a/source/auxiliary/sbasic.tree b/source/auxiliary/sbasic.tree
index 8ecb215a0..308f10f99 100644
--- a/source/auxiliary/sbasic.tree
+++ b/source/auxiliary/sbasic.tree
@@ -338,6 +338,7 @@
<node id="070202" title="Programming with Python">
<topic
id="sbasic/text/sbasic/python/python_programming.xhp">Programming with Python
Scripts</topic>
<topic
id="sbasic/text/sbasic/python/python_examples.xhp">Python Programming
Examples</topic>
+ <topic
id="sbasic/text/sbasic/python/python_2_basic.xhp">Calling Basic Macros from
Python</topic>
</node>
</node>
</help_section>
diff --git a/source/text/sbasic/python/python_2_basic.xhp
b/source/text/sbasic/python/python_2_basic.xhp
new file mode 100644
index 000000000..7be490b75
--- /dev/null
+++ b/source/text/sbasic/python/python_2_basic.xhp
@@ -0,0 +1,151 @@
+<?xml version="1.0" encoding="UTF-8"?>
+ <!--
+ * 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/.
+ *
+ -->
+<helpdocument version="1.0">
+ <meta>
+ <topic id="python_2_basic">
+ <title id="tit" xml-lang="en-US">Python to Basic</title>
+ <filename>/text/sbasic/python/python_2_basic.xhp</filename>
+ </topic>
+ </meta>
+ <body>
+ <bookmark branch="index" id="N0330">
+ <bookmark_value>Python;Calling Basic</bookmark_value>
+ <bookmark_value>ParamArray</bookmark_value>
+ </bookmark>
+ <h1 id="N0331"><variable id="py2ba_h1"><link
href="text/sbasic/python/python_2_basic.xhp" name="Calling Basic macros from
Python">Calling Basic Macros from Python</link></variable></h1>
+ <paragraph role="paragraph" id="N0332">You can call %PRODUCTNAME
Basic macros from Python scripts, and notable features can be obtained in
return such as:</paragraph>
+ <list type="unordered">
+ <listitem><paragraph role="listitem" id="N0333">Simple logging
facilities out of <literal>Access2Base</literal> library Trace
console,</paragraph></listitem>
+ <listitem><paragraph role="listitem"
id="N0334"><literal>InputBox</literal> and <literal>MsgBox</literal> screen I/O
functions based on Basic to ease Python development,</paragraph></listitem>
+ <listitem><paragraph role="listitem"
id="N0335"><literal>Xray</literal> calls interrupting Python script execution
to help inspect variables.</paragraph></listitem>
+ </list>
+ <section id="APIScriptingFramework" >
+ <paragraph role="paragraph" id="N0336"> The %PRODUCTNAME
Application Programming Interface (API) Scripting Framework supports
inter-language script execution between Python and Basic, or other supported
programming languages for that matter. Arguments can be passed back and fourth
across calls, providing they represent primitives data types that both
languages recognize, and assuming that the Scripting Framework converts them
appropriately.</paragraph>
+ </section>
+ <tip id="N0337">It is recommended to have knowledge of Python
standard modules and %PRODUCTNAME API features prior to perform inter-language
calls from Python to Basic, JavaScript or any other script engine.</tip>
+ <warning id="N0338">When running Python scripts from an Integrated
Development Environment (IDE), the %PRODUCTNAME nested Basic engine is absent.
Avoid Python to %PRODUCTNAME Basic calls in this context. However Python
environment and Universal Networks Objects (UNO) are fully available. Refer to
<link href="text/sbasic/python/python_ide.xhp" name ="external">Setting Up an
Integrated IDE for Python</link> for more information.</warning>
+ <h2 id="N0339">Retrieving %PRODUCTNAME Basic Scripts</h2>
+ <paragraph role="paragraph" id="N0340">%PRODUCTNAME Basic macros can
be personal, shared, or embedded in documents. In order to execute them, Python
run time needs to be provided with Basic macro locations. Implementing the
<link
href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1script_1_1provider_1_1XScript.html";
name ="external">com.sun.star.script.provider.XScriptProvider</link> interface
allows the retrieval of executable scripts:</paragraph>
+ <section id="Python_getBasicScript" >
+ <bookmark branch="index" id="N0341">
+
<bookmark_value>API;script.provider.MasterScriptProviderFactory: Retrieving
Basic scripts</bookmark_value>
+ <bookmark_value>API;script.provider.XScript : Executing
Basic scripts</bookmark_value>
+ <bookmark_value>API;XScriptProvider: Retrieving Basic
scripts</bookmark_value>
+ </bookmark>
+ <pycode>
+ <paragraph role="pycode" id="N0342">import uno</paragraph>
+ <paragraph role="pycode" id="N0343">from
com.sun.star.script.provider import Xscript</paragraph>
+ <paragraph role="pycode" id="N0344"> </paragraph>
+ <paragraph role="pycode" id="N0345">def
getBasicScript(macro='Main', module='Module1',
library='Standard',</paragraph>
+ <paragraph role="pycode" id="N0346"> isEmbedded=False)
-> XScript:</paragraph>
+ <paragraph role="pycode" id="N0347"> '''Grab
Basic script object before invocation.'''</paragraph>
+ <paragraph role="pycode" id="N0348"> ctx =
uno.getComponentContext()</paragraph>
+ <paragraph role="pycode" id="N0349"> smgr =
ctx.ServiceManager</paragraph>
+ <paragraph role="pycode" id="N0350"> if
isEmbedded:</paragraph>
+ <paragraph role="pycode" id="N0351"> desktop =
smgr.createInstanceWithContext('com.sun.star.frame.Desktop',
ctx)</paragraph>
+ <paragraph role="pycode" id="N0352"> scriptPro =
desktop.CurrentComponent.getScriptProvider()</paragraph>
+ <paragraph role="pycode" id="N0353"> location =
"document"</paragraph>
+ <paragraph role="pycode" id="N0354"> else:</paragraph>
+ <paragraph role="pycode" id="N0355"> mspf =
smgr.createInstanceWithContext(</paragraph>
+ <paragraph role="pycode" id="N0356">
"com.sun.star.script.provider.MasterScriptProviderFactory",
ctx)</paragraph>
+ <paragraph role="pycode" id="N0357"> scriptPro =
mspf.createScriptProvider("")</paragraph>
+ <paragraph role="pycode" id="N0358"> location =
"application"</paragraph>
+ <paragraph role="pycode" id="N0359"> scriptName =
"vnd.sun.star.script:"+library+"."+module+"."+macro+
\</paragraph>
+ <paragraph role="pycode" id="N0360">
"?language=Basic&location="+location</paragraph>
+ <paragraph role="pycode" id="N0361"> xScript =
scriptPro.getScript(scriptName)</paragraph>
+ <paragraph role="pycode" id="N0362"> return
xScript</paragraph>
+ </pycode>
+ </section>
+ <h2 id="N0363">Executing %PRODUCTNAME Basic Scripts</h2>
+ <section id="APIScriptingFramework_XScript" >
+ <bookmark branch="index" id="N0364ndx">
+ <bookmark_value>API;script.provider.XScript : Executing
Basic scripts</bookmark_value>
+ </bookmark>
+ <paragraph role="paragraph" id="N0364">The %PRODUCTNAME
Software Development Kit (SDK) documentation for <link
href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1script_1_1provider_1_1XScript.html#a11a551f5a2520f74c5109cd8c9f8c7b7";
name ="external">com.sun.star.script.provider.XScript</link> interface details
the calling convention for inter-language calls. Invocation of functions
requires three arrays:</paragraph>
+ <list type="unordered">
+ <listitem><paragraph role="listitem" id="N0365">the
first lists the arguments of the called routine</paragraph></listitem>
+ <listitem><paragraph role="listitem" id="N0366">the
second identifies modified arguments</paragraph></listitem>
+ <listitem><paragraph role="listitem" id="N0367">the
third stores the return values</paragraph></listitem>
+ </list>
+ </section>
+ <h3 id="N0368">Python Syntax</h3>
+ <paragraph role="paragraph" id="N0369"><literal>results =
script.invoke((prompt,buttons,title), (), ())</literal></paragraph>
+ <paragraph role="paragraph"
id="N0370"><literal>script.invoke((message,), tuple, ())</literal></paragraph>
+ <paragraph role="paragraph" id="N0371"><literal>script.invoke((args),
(), results)</literal></paragraph>
+ <h3 id="N0372">Examples of Personal or Shared Scripts</h3>
+ <paragraph role="paragraph" id="N0373">Examples in <link
href="text/sbasic/python/python_screen.xhp" name ="external">Input/Output to
Screen</link> details Python to Basic invocation calls. <link
href="text/sbasic/python/python_document_events.xhp" name
="external">Monitoring Document Events</link> illustrates the usage of *args
Python idiom to print a variable number of parameters to
<literal>Access2Base</literal> logging console dialog.</paragraph>
+ <tip id="N0374">At time of development you can interrupt Python
script execution using <link
href="https://berma.pagesperso-orange.fr/index2.html"; name ="external">Xray
extension</link> in order to inspect properties and methods of UNO objects. The
ASPO extension debugger allows object introspection using either Xray either
MRI extensions.</tip>
+ <pycode>
+ <paragraph role="pycode" id="N0375">def xray(myObject):</paragraph>
+ <paragraph role="pycode" id="N0376"> script =
getBasicScript(library="XrayTool", module="_Main",
macro="Xray")</paragraph>
+ <paragraph role="pycode" id="N0377"> script.invoke((myObject,),
(), ())</paragraph>
+ </pycode>
+ <h3 id="N0378">Examples of Embedded Scripts in Documents</h3>
+ <paragraph role="paragraph" id="N0379"><literal>*args</literal>Python
simplified syntax can be used in conjunction with %PRODUCTNAME Basic routines
that accept a variable number of arguments. Below <literal>Print</literal> and
<literal>SUM</literal> Python functions call their Basic
<literal>Print</literal> and <literal>SUM</literal> counterparts, using
aforementioned <literal>getBasicScript</literal> function. Exception handling
is not detailed.</paragraph>
+ <pycode>
+ <paragraph role="pycode" id="N0380"># -*- coding: utf-8
-*-</paragraph>
+ <paragraph role="pycode" id="N0381">from __future__ import
unicode_literals</paragraph>
+ <paragraph role="pycode" id="N0382"> </paragraph>
+ <paragraph role="pycode" id="N0383">def Print(*args):</paragraph>
+ <paragraph role="pycode" id="N0384"> """Outputs the
specified strings or numeric expressions in a dialog
box."""</paragraph>
+ <paragraph role="pycode" id="N0385"> xScript =
getBasicScript("Print", "Scripting",
embedded=True)</paragraph>
+ <paragraph role="pycode" id="N0386"> xScript.invoke((args), (),
())</paragraph>
+ <paragraph role="pycode" id="N0387"> </paragraph>
+ <paragraph role="pycode" id="N0388">def SUM(*args):</paragraph>
+ <paragraph role="pycode" id="N0389"> """SUM the
specified number expression."""</paragraph>
+ <paragraph role="pycode" id="N0390"> xScript =
getBasicScript("SUM", "Scripting",
embedded=True)</paragraph>
+ <paragraph role="pycode" id="N0391"> res = xScript.invoke((args),
(), ())</paragraph>
+ <paragraph role="pycode" id="N0392"> return res[0]</paragraph>
+ <paragraph role="pycode" id="N0393"> </paragraph>
+ <paragraph role="pycode" id="N0394"># def getBasicScript() # see
above</paragraph>
+ <paragraph role="pycode" id="N0395"> </paragraph>
+ <paragraph role="pycode" id="N0396">def playWithArgs():</paragraph>
+ <paragraph role="pycode" id="N0397"> Print("Fun with *args
", -9.81, 297864.681974, 8762E-137)</paragraph>
+ <paragraph role="pycode" id="N0398"> Print(SUM(45, -9.81,
297864.681974))</paragraph>
+ <paragraph role="pycode" id="N0399"> Print(SUM(45, -9.81,
297864.681974, 8762E+137))</paragraph>
+ <paragraph role="pycode" id="N0400"> </paragraph>
+ <paragraph role="pycode" id="N0401">g_exportedScripts =
(playWithArgs,)</paragraph>
+ </pycode>
+ <paragraph role="paragraph" id="N0402">The %PRODUCTNAME Basic
<literal>Print</literal> and <literal>SUM</literal> document-based routines
accept a variable number of arguments. The <literal>Private</literal> or
<literal>Public</literal> attributes have no effect. The arguments type
checking is skipped for clarity.</paragraph>
+ <bascode>
+ <paragraph role="bascode" id="N0403">Option Compatible '
"Standard.Scripting" module</paragraph>
+ <paragraph role="bascode" id="N0404">Option Explicit</paragraph>
+ <paragraph role="bascode" id="N0405"> </paragraph>
+ <paragraph role="bascode" id="N0406">Private Sub Print(ParamArray
args() As Variant, Optional sep As String = " ")</paragraph>
+ <paragraph role="bascode" id="N0407"> ''' Print
item list of variable number '''</paragraph>
+ <paragraph role="bascode" id="N0408"> ' all CStr()
convertible args are accepted</paragraph>
+ <paragraph role="bascode" id="N0409"> Dim str As String, i As
Integer</paragraph>
+ <paragraph role="bascode" id="N0410"> If UBound(args) >= 0
Then</paragraph>
+ <paragraph role="bascode" id="N0411"> For i = 0 To
UBound(args)</paragraph>
+ <paragraph role="bascode" id="N0412"> str = str +
Cstr(args(i))+ sep </paragraph>
+ <paragraph role="bascode" id="N0413"> Next i</paragraph>
+ <paragraph role="bascode" id="N0414"> End If</paragraph>
+ <paragraph role="bascode" id="N0415"> Print str</paragraph>
+ <paragraph role="bascode" id="N0416"> End Sub '
Standard.Scripting.Print()</paragraph>
+ <paragraph role="bascode" id="N0417"> </paragraph>
+ <paragraph role="bascode" id="N0418">Public Function SUM(ParamArray
args() As Variant) As Variant</paragraph>
+ <paragraph role="bascode" id="N0419"> ''' SUM a
variable list of numbers '''</paragraph>
+ <paragraph role="bascode" id="N0420"> Dim ndx As
Integer</paragraph>
+ <paragraph role="bascode" id="N0421"> If UBound(args) >= 0
Then</paragraph>
+ <paragraph role="bascode" id="N0422"> For ndx = 0 To
UBound(args)</paragraph>
+ <paragraph role="bascode" id="N0423"> SUM = SUM +
args(ndx)</paragraph>
+ <paragraph role="bascode" id="N0424"> Next ndx</paragraph>
+ <paragraph role="bascode" id="N0425"> End If</paragraph>
+ <paragraph role="bascode" id="N0426">End Function '
Standard.Scripting.SUM()</paragraph>
+ </bascode>
+ <section id="relatedtopics" >
+ <!-- WIP
+ <paragraph role="paragraph" id="N0427">Calling Python macros
from Basic</paragraph>
+ -->
+ <embed
href="text/sbasic/python/python_examples.xhp#pythonexamples2"/>
+ <embed
href="text/sbasic/python/main0000.xhp#pythonscriptshelp"/>
+ </section>
+ </body>
+</helpdocument>
diff --git a/source/text/sbasic/python/python_document_events.xhp
b/source/text/sbasic/python/python_document_events.xhp
index 873a85d0a..49e7303d4 100644
--- a/source/text/sbasic/python/python_document_events.xhp
+++ b/source/text/sbasic/python/python_document_events.xhp
@@ -25,7 +25,7 @@
<bookmark_value>API;document.DocumentEvent: Monitoring Document
Event</bookmark_value>
<bookmark_value>API;document.XDocumentEventBroadcaster: Monitoring
Document Event</bookmark_value>
<bookmark_value>API;document.XDocumentEventListener: Monitoring
Document Event</bookmark_value>
- <bookmark_value>API;frame.Desktop: Monitoring Document
Event</bookmark_value>
+ <bookmark_value>API;frame.Desktop: Monitoring Document
Event</bookmark_value>
<bookmark_value>API;frame.GlobalEventBroadcaster: Monitoring Document
Event</bookmark_value>
<bookmark_value>API;lang.EventObject: Monitoring Document
Event</bookmark_value>
<bookmark_value>API;script.provider.MasterScriptProviderFactory:
Monitoring Document Event</bookmark_value>
@@ -272,6 +272,7 @@
-->
<embed href="text/sbasic/python/python_examples.xhp#pythonexamples2"/>
<embed
href="text/sbasic/python/python_programming.xhp#pythonprogrammingheading"/>
+ <embed href="text/sbasic/python/python_2_basic.xhp#py2ba_h1"/>
</section>
</body>
</helpdocument>
diff --git a/source/text/sbasic/python/python_examples.xhp
b/source/text/sbasic/python/python_examples.xhp
index f7d45f573..84330a640 100644
--- a/source/text/sbasic/python/python_examples.xhp
+++ b/source/text/sbasic/python/python_examples.xhp
@@ -36,6 +36,7 @@
<embed href="text/sbasic/python/python_document_events.xhp#pythonmonitor"/>
<embed href="text/sbasic/python/python_dialogs.xhp#pythondialog"/>
<embed href="text/sbasic/python/python_listener.xhp#pythonlistener"/>
+ <embed href="text/sbasic/python/python_2_basic.xhp#py2ba_h1"/>
<section id="relatedtopics">
<embed href="text/sbasic/python/main0000.xhp#pythonscriptshelp"/>
</section>
diff --git a/source/text/sbasic/python/python_screen.xhp
b/source/text/sbasic/python/python_screen.xhp
index f3ee2ce9f..ed5591711 100644
--- a/source/text/sbasic/python/python_screen.xhp
+++ b/source/text/sbasic/python/python_screen.xhp
@@ -102,6 +102,7 @@
<embed href="text/sbasic/shared/03010000.xhp#BasicScreenIO"/>
<embed href="text/sbasic/python/python_examples.xhp#pythonexamples2"/>
<embed href="text/sbasic/python/main0000.xhp#pythonscriptshelp"/>
+ <embed href="text/sbasic/python/python_2_basic.xhp#py2ba_h1"/>
</section>
</body>
</helpdocument>
commit 15790ee596f22dcea3ddcdacdc56113ec54b63f3
Author: Olivier Hallot <olivier.hal...@libreoffice.org>
AuthorDate: Fri Jul 12 16:34:34 2019 +0200
Commit: Olivier Hallot <olivier.hal...@libreoffice.org>
CommitDate: Mon Jul 15 02:23:33 2019 +0200
Clarify example for SWITCH
...But the function need a date in A3 instead of a number.
So in my opinion the string should be:
<input>=SWITCH(MONTH(A3),1,"January",2,"February",3,"March","No
match")</input> returns "January" when A3 contains a date in January,
"February" when A3 contains a date in February , etc...
Change-Id: I2702d569f1c43080cd4c137a4d100111edc55863
Reviewed-on: https://gerrit.libreoffice.org/75499
Tested-by: Jenkins
Reviewed-by: Olivier Hallot <olivier.hal...@libreoffice.org>
diff --git a/source/text/scalc/01/func_switch.xhp
b/source/text/scalc/01/func_switch.xhp
index 36178c1be..2c162d2ae 100644
--- a/source/text/scalc/01/func_switch.xhp
+++ b/source/text/scalc/01/func_switch.xhp
@@ -33,7 +33,7 @@
<paragraph role="paragraph"
id="par_id331556245422283"><emph>default_result</emph>: any value or reference
to a cell that is returned when there is no match.</paragraph>
<paragraph role="paragraph" id="par_id871556243022881">If no
<emph>value</emph> equals <emph>expression</emph> and no default result is
given, a #N/A error is returned.</paragraph>
<embed href="text/scalc/01/ful_func.xhp#func_head_example"/>
- <paragraph role="paragraph"
id="par_id851556243961783"><input>=SWITCH(MONTH(A3),1,"January",2,"February",3,"March","No
match")</input> returns "January" when A3=1, February when A3=2 ,
etc...</paragraph>
+ <paragraph role="paragraph"
id="par_id851556243961783"><input>=SWITCH(MONTH(A3),1,"January",2,"February",3,"March","No
match")</input> returns "January" when A3 contains a date in January,
"February" when A3 contains a date in February , etc...</paragraph>
<section id="relatedtopics">
<embed href="text/scalc/01/func_ifs.xhp#ifsfunct"/>
<paragraph role="paragraph" id="par_id781556244709752"><link
href="text/scalc/01/04060105.xhp#Section4" name="if">IF</link></paragraph>
_______________________________________________
Libreoffice-commits mailing list
libreoffice-comm...@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/libreoffice-commits
