diff options
| author | LibreOfficiant <LibreOfficiant@sfr.fr> | 2019-07-03 19:43:26 +0200 |
|---|---|---|
| committer | Olivier Hallot <olivier.hallot@libreoffice.org> | 2019-07-15 02:23:47 +0200 |
| commit | 3d1c81107309511f00a024a2e1a706a8bf96af47 (patch) | |
| tree | c43bf8f3efa50dd1aac2c4d7cc2dea7be867ed5e /source/text | |
| parent | 15790ee596f22dcea3ddcdacdc56113ec54b63f3 (diff) | |
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.hallot@libreoffice.org>
Diffstat (limited to 'source/text')
| -rw-r--r-- | source/text/sbasic/python/python_2_basic.xhp | 151 | ||||
| -rw-r--r-- | source/text/sbasic/python/python_document_events.xhp | 3 | ||||
| -rw-r--r-- | source/text/sbasic/python/python_examples.xhp | 1 | ||||
| -rw-r--r-- | source/text/sbasic/python/python_screen.xhp | 1 |
4 files changed, 155 insertions, 1 deletions
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 0000000000..7be490b75b --- /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 873a85d0a1..49e7303d4d 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 f7d45f5737..84330a6400 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 f3ee2ce9fc..ed5591711c 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> |