From 3d1c81107309511f00a024a2e1a706a8bf96af47 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?LibreO=EF=AC=83ciant?= Date: Wed, 3 Jul 2019 19:43:26 +0200 Subject: [PATCH] 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 --- AllLangHelp_sbasic.mk | 1 + source/auxiliary/sbasic.tree | 1 + source/text/sbasic/python/python_2_basic.xhp | 151 ++++++++++++++++++ .../sbasic/python/python_document_events.xhp | 3 +- source/text/sbasic/python/python_examples.xhp | 1 + source/text/sbasic/python/python_screen.xhp | 1 + 6 files changed, 157 insertions(+), 1 deletion(-) create mode 100644 source/text/sbasic/python/python_2_basic.xhp diff --git a/AllLangHelp_sbasic.mk b/AllLangHelp_sbasic.mk index a1f3fed2cc..1cac18fe40 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 8ecb215a07..308f10f997 100644 --- a/source/auxiliary/sbasic.tree +++ b/source/auxiliary/sbasic.tree @@ -338,6 +338,7 @@ Programming with Python Scripts Python Programming Examples + Calling Basic Macros from Python 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 @@ + + + + + + Python to Basic + /text/sbasic/python/python_2_basic.xhp + + + + + Python;Calling Basic + ParamArray + +

Calling Basic Macros from Python

+ You can call %PRODUCTNAME Basic macros from Python scripts, and notable features can be obtained in return such as: + + Simple logging facilities out of Access2Base library Trace console, + InputBox and MsgBox screen I/O functions based on Basic to ease Python development, + Xray calls interrupting Python script execution to help inspect variables. + +
+ 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. +
+ 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. + 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 Setting Up an Integrated IDE for Python for more information. +

Retrieving %PRODUCTNAME Basic Scripts

+ %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 com.sun.star.script.provider.XScriptProvider interface allows the retrieval of executable scripts: +
+ + API;script.provider.MasterScriptProviderFactory: Retrieving Basic scripts + API;script.provider.XScript : Executing Basic scripts + API;XScriptProvider: Retrieving Basic scripts + + + import uno + from com.sun.star.script.provider import Xscript + + def getBasicScript(macro='Main', module='Module1', library='Standard', + isEmbedded=False) -> XScript: + '''Grab Basic script object before invocation.''' + ctx = uno.getComponentContext() + smgr = ctx.ServiceManager + if isEmbedded: + desktop = smgr.createInstanceWithContext('com.sun.star.frame.Desktop', ctx) + scriptPro = desktop.CurrentComponent.getScriptProvider() + location = "document" + else: + mspf = smgr.createInstanceWithContext( + "com.sun.star.script.provider.MasterScriptProviderFactory", ctx) + scriptPro = mspf.createScriptProvider("") + location = "application" + scriptName = "vnd.sun.star.script:"+library+"."+module+"."+macro+ \ + "?language=Basic&location="+location + xScript = scriptPro.getScript(scriptName) + return xScript + +
+

Executing %PRODUCTNAME Basic Scripts

+
+ + API;script.provider.XScript : Executing Basic scripts + + The %PRODUCTNAME Software Development Kit (SDK) documentation for com.sun.star.script.provider.XScript interface details the calling convention for inter-language calls. Invocation of functions requires three arrays: + + the first lists the arguments of the called routine + the second identifies modified arguments + the third stores the return values + +
+

Python Syntax

+ results = script.invoke((prompt,buttons,title), (), ()) + script.invoke((message,), tuple, ()) + script.invoke((args), (), results) +

Examples of Personal or Shared Scripts

+ Examples in Input/Output to Screen details Python to Basic invocation calls. Monitoring Document Events illustrates the usage of *args Python idiom to print a variable number of parameters to Access2Base logging console dialog. + At time of development you can interrupt Python script execution using Xray extension in order to inspect properties and methods of UNO objects. The ASPO extension debugger allows object introspection using either Xray either MRI extensions. + + def xray(myObject): + script = getBasicScript(library="XrayTool", module="_Main", macro="Xray") + script.invoke((myObject,), (), ()) + +

Examples of Embedded Scripts in Documents

+ *argsPython simplified syntax can be used in conjunction with %PRODUCTNAME Basic routines that accept a variable number of arguments. Below Print and SUM Python functions call their Basic Print and SUM counterparts, using aforementioned getBasicScript function. Exception handling is not detailed. + + # -*- coding: utf-8 -*- + from __future__ import unicode_literals + + def Print(*args): + """Outputs the specified strings or numeric expressions in a dialog box.""" + xScript = getBasicScript("Print", "Scripting", embedded=True) + xScript.invoke((args), (), ()) + + def SUM(*args): + """SUM the specified number expression.""" + xScript = getBasicScript("SUM", "Scripting", embedded=True) + res = xScript.invoke((args), (), ()) + return res[0] + + # def getBasicScript() # see above + + def playWithArgs(): + Print("Fun with *args ", -9.81, 297864.681974, 8762E-137) + Print(SUM(45, -9.81, 297864.681974)) + Print(SUM(45, -9.81, 297864.681974, 8762E+137)) + + g_exportedScripts = (playWithArgs,) + + The %PRODUCTNAME Basic Print and SUM document-based routines accept a variable number of arguments. The Private or Public attributes have no effect. The arguments type checking is skipped for clarity. + + Option Compatible ' "Standard.Scripting" module + Option Explicit + + Private Sub Print(ParamArray args() As Variant, Optional sep As String = " ") + ''' Print item list of variable number ''' + ' all CStr() convertible args are accepted + Dim str As String, i As Integer + If UBound(args) >= 0 Then + For i = 0 To UBound(args) + str = str + Cstr(args(i))+ sep + Next i + End If + Print str + End Sub ' Standard.Scripting.Print() + + Public Function SUM(ParamArray args() As Variant) As Variant + ''' SUM a variable list of numbers ''' + Dim ndx As Integer + If UBound(args) >= 0 Then + For ndx = 0 To UBound(args) + SUM = SUM + args(ndx) + Next ndx + End If + End Function ' Standard.Scripting.SUM() + +
+ + + +
+ + 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 @@ API;document.DocumentEvent: Monitoring Document Event API;document.XDocumentEventBroadcaster: Monitoring Document Event API;document.XDocumentEventListener: Monitoring Document Event - API;frame.Desktop: Monitoring Document Event + API;frame.Desktop: Monitoring Document Event API;frame.GlobalEventBroadcaster: Monitoring Document Event API;lang.EventObject: Monitoring Document Event API;script.provider.MasterScriptProviderFactory: Monitoring Document Event @@ -272,6 +272,7 @@ --> + 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 @@ +
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 @@ +