diff options
Diffstat (limited to 'helpcontent2/source/text/sbasic/python')
15 files changed, 1913 insertions, 0 deletions
diff --git a/helpcontent2/source/text/sbasic/python/main0000.xhp b/helpcontent2/source/text/sbasic/python/main0000.xhp new file mode 100644 index 000000000..867cd1ad4 --- /dev/null +++ b/helpcontent2/source/text/sbasic/python/main0000.xhp @@ -0,0 +1,44 @@ +<?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="pythonmain0000" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">Python Scripts</title> + <filename>/text/sbasic/python/main0000.xhp</filename> + </topic> + </meta> + <body> + <bookmark xml-lang="en-US" branch="index" id="bm_id491543348147708"> + <bookmark_value>macros;Python scripts</bookmark_value> + <bookmark_value>Python;macros</bookmark_value> + <bookmark_value>scripts;Python</bookmark_value> + </bookmark> + <h1 id="hd_id3154232"><variable id="pythonscriptshelp"><link href="text/sbasic/python/main0000.xhp" name="mainpython">%PRODUCTNAME Python Scripts Help</link></variable></h1> + + <section id="pythonalt"> + <paragraph id="par_id3153894" role="paragraph" xml-lang="en-US">%PRODUCTNAME provides an Application Programming Interface (API) that allows controlling the $[officename] components with different programming languages by using the $[officename] Software Development Kit (SDK). For more information about the $[officename] API and the Software Development Kit, visit <link href="https://api.libreoffice.org/" name="api.libreoffice.org">https://api.libreoffice.org</link></paragraph> + <paragraph id="par_id3147226" role="paragraph" xml-lang="en-US">This help section explains the most common Python script functions for %PRODUCTNAME. For more in-depth information please refer to the <link href="https://wiki.documentfoundation.org/Macros/Python_Design_Guide" name="wiki.documentfoundation.org PYTHON Guide">Designing & Developing Python Applications</link> on the Wiki.</paragraph> + </section> + <h2 id="hd_id3146957">Working with Python Scripts in %PRODUCTNAME</h2> + <paragraph role="paragraph" id="N0102">You can execute Python scripts choosing <menuitem>Tools - Macros - Run Macro</menuitem>. Editing scripts can be done with your preferred text editor. Python scripts are present in various locations detailed hereafter. You can refer to Programming examples for macros illustrating how to run the Python interactive console from %PRODUCTNAME.</paragraph> + <switch select="sys"> + <case select="UNIX"> + <warning id="par_id131568902936659">The %PRODUCTNAME scripting framework for Python is optional on some GNU/Linux distributions. If it is installed, selecting <menuitem>Tools - Macros - Run Macro...</menuitem> and checking <literal>%PRODUCTNAME Macros</literal> for the presence of <literal>HelloWorld – HelloWorldPython</literal> macro is sufficient. If absent, please refer to your distribution documentation in order to install the %PRODUCTNAME scripting framework for Python.</warning> + </case> + </switch> + <embed href="text/shared/guide/scripting.xhp#scripting"/> + <embed href="text/sbasic/python/python_ide.xhp#pythonideh1"/> + <embed href="text/sbasic/python/python_locations.xhp#pythonlocations1"/> + <embed href="text/sbasic/python/python_shell.xhp#pythonshell1"/> + <embed href="text/sbasic/python/python_programming.xhp#pythonprogrammingheading"/> + <embed href="text/sbasic/python/python_examples.xhp#pythonexamples2"/> + <embed href="text/swriter/main0000.xhp#helpabouthelp"/> +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/python/python_2_basic.xhp b/helpcontent2/source/text/sbasic/python/python_2_basic.xhp new file mode 100644 index 000000000..60d31312a --- /dev/null +++ b/helpcontent2/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> + <!-- WIP - Context clarifications needed in below warning --> + <warning id="N0338">When running Python scripts from an Integrated Development Environment (IDE), the %PRODUCTNAME nested Basic engine may be absent. Avoid Python to %PRODUCTNAME Basic calls in such context. However Python environment and Universal Networks Objects (UNO) are fully available. Refer to <link href="text/sbasic/python/python_ide.xhp" name ="Setting Up an Integrated IDE for Python">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 ="XScriptProvider interface">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" localize="false">import uno</paragraph> + <paragraph role="pycode" id="N0343" localize="false">from com.sun.star.script.provider import Xscript</paragraph> + <paragraph role="pycode" id="N0344" localize="false"> </paragraph> + <paragraph role="pycode" id="N0345" localize="false">def getBasicScript(macro='Main', module='Module1', library='Standard',</paragraph> + <paragraph role="pycode" id="N0346" localize="false"> isEmbedded=False) -> XScript:</paragraph> + <paragraph role="pycode" id="N0347"> '''Grab Basic script object before invocation.'''</paragraph> + <paragraph role="pycode" id="N0348" localize="false"> ctx = uno.getComponentContext()</paragraph> + <paragraph role="pycode" id="N0349" localize="false"> smgr = ctx.ServiceManager</paragraph> + <paragraph role="pycode" id="N0350" localize="false"> if isEmbedded:</paragraph> + <paragraph role="pycode" id="N0351" localize="false"> desktop = smgr.createInstanceWithContext('com.sun.star.frame.Desktop', ctx)</paragraph> + <paragraph role="pycode" id="N0352" localize="false"> scriptPro = desktop.CurrentComponent.getScriptProvider()</paragraph> + <paragraph role="pycode" id="N0353" localize="false"> location = "document"</paragraph> + <paragraph role="pycode" id="N0354" localize="false"> else:</paragraph> + <paragraph role="pycode" id="N0355" localize="false"> mspf = smgr.createInstanceWithContext(</paragraph> + <paragraph role="pycode" id="N0356" localize="false"> "com.sun.star.script.provider.MasterScriptProviderFactory", ctx)</paragraph> + <paragraph role="pycode" id="N0357" localize="false"> scriptPro = mspf.createScriptProvider("")</paragraph> + <paragraph role="pycode" id="N0358" localize="false"> location = "application"</paragraph> + <paragraph role="pycode" id="N0359" localize="false"> scriptName = "vnd.sun.star.script:"+library+"."+module+"."+macro+ \</paragraph> + <paragraph role="pycode" id="N0360" localize="false"> "?language=Basic&location="+location</paragraph> + <paragraph role="pycode" id="N0361" localize="false"> xScript = scriptPro.getScript(scriptName)</paragraph> + <paragraph role="pycode" id="N0362" localize="false"> 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 ="XScript interface">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 ="Input/Output to Screen">Input/Output to Screen</link> detail Python to Basic invocation calls. <link href="text/sbasic/python/python_document_events.xhp" name ="Monitoring Document Events">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 ="Xray extension">Xray extension</link> in order to inspect properties and methods of UNO objects. The APSO extension debugger allows object introspection using either Xray either MRI extensions.</tip> + <pycode> + <paragraph role="pycode" id="N0375" localize="false">def xray(myObject):</paragraph> + <paragraph role="pycode" id="N0376" localize="false"> script = getBasicScript(library="XrayTool", module="_Main", macro="Xray")</paragraph> + <paragraph role="pycode" id="N0377" localize="false"> 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" localize="false"># -*- coding: utf-8 -*-</paragraph> + <paragraph role="pycode" id="N0381" localize="false">from __future__ import unicode_literals</paragraph> + <paragraph role="pycode" id="N0382" localize="false"> </paragraph> + <paragraph role="pycode" id="N0383" localize="false">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" localize="false"> xScript = getBasicScript("Print", "Scripting", embedded=True)</paragraph> + <paragraph role="pycode" id="N0386" localize="false"> xScript.invoke((args), (), ())</paragraph> + <paragraph role="pycode" id="N0387" localize="false"> </paragraph> + <paragraph role="pycode" id="N0388" localize="false">def SUM(*args):</paragraph> + <paragraph role="pycode" id="N0389"> """SUM the specified number expression."""</paragraph> + <paragraph role="pycode" id="N0390" localize="false"> xScript = getBasicScript("SUM", "Scripting", embedded=True)</paragraph> + <paragraph role="pycode" id="N0391" localize="false"> res = xScript.invoke((args), (), ())</paragraph> + <paragraph role="pycode" id="N0392" localize="false"> return res[0]</paragraph> + <paragraph role="pycode" id="N0393" localize="false"> </paragraph> + <paragraph role="pycode" id="N0394" localize="false"># def getBasicScript() # see above</paragraph> + <paragraph role="pycode" id="N0395" localize="false"> </paragraph> + <paragraph role="pycode" id="N0396" localize="false">def playWithArgs():</paragraph> + <paragraph role="pycode" id="N0397" localize="false"> Print("Fun with *args ", -9.81, 297864.681974, 8762E-137)</paragraph> + <paragraph role="pycode" id="N0398" localize="false"> Print(SUM(45, -9.81, 297864.681974))</paragraph> + <paragraph role="pycode" id="N0399" localize="false"> Print(SUM(45, -9.81, 297864.681974, 8762E+137))</paragraph> + <paragraph role="pycode" id="N0400" localize="false"> </paragraph> + <paragraph role="pycode" id="N0401" localize="false">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" localize="false">Option Compatible ' "Standard.Scripting" module</paragraph> + <paragraph role="bascode" id="N0404" localize="false">Option Explicit</paragraph> + <paragraph role="bascode" id="N0405" localize="false"> </paragraph> + <paragraph role="bascode" id="N0406" localize="false">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" localize="false"> Dim str As String, i As Integer</paragraph> + <paragraph role="bascode" id="N0410" localize="false"> If UBound(args) >= 0 Then</paragraph> + <paragraph role="bascode" id="N0411" localize="false"> For i = 0 To UBound(args)</paragraph> + <paragraph role="bascode" id="N0412" localize="false"> str = str + Cstr(args(i))+ sep </paragraph> + <paragraph role="bascode" id="N0413" localize="false"> Next i</paragraph> + <paragraph role="bascode" id="N0414" localize="false"> End If</paragraph> + <paragraph role="bascode" id="N0415" localize="false"> Print str</paragraph> + <paragraph role="bascode" id="N0416" localize="false"> End Sub ' Standard.Scripting.Print()</paragraph> + <paragraph role="bascode" id="N0417" localize="false"> </paragraph> + <paragraph role="bascode" id="N0418" localize="false">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" localize="false"> Dim ndx As Integer</paragraph> + <paragraph role="bascode" id="N0421" localize="false"> If UBound(args) >= 0 Then</paragraph> + <paragraph role="bascode" id="N0422" localize="false"> For ndx = 0 To UBound(args)</paragraph> + <paragraph role="bascode" id="N0423" localize="false"> SUM = SUM + args(ndx)</paragraph> + <paragraph role="bascode" id="N0424" localize="false"> Next ndx</paragraph> + <paragraph role="bascode" id="N0425" localize="false"> End If</paragraph> + <paragraph role="bascode" id="N0426" localize="false">End Function ' Standard.Scripting.SUM()</paragraph> + </bascode> + <section id="relatedtopics" > + <embed href="text/sbasic/guide/basic_2_python.xhp#basic2python"/> + <embed href="text/sbasic/python/python_examples.xhp#pythonexamples2"/> + <embed href="text/sbasic/python/main0000.xhp#pythonscriptshelp"/> + <embed href="text/sbasic/shared/main0601.xhp#mainsbasic"/> + </section> + </body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/python/python_dialogs.xhp b/helpcontent2/source/text/sbasic/python/python_dialogs.xhp new file mode 100644 index 000000000..7f728b495 --- /dev/null +++ b/helpcontent2/source/text/sbasic/python/python_dialogs.xhp @@ -0,0 +1,75 @@ +<?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="text/sbasic/python/Python_Dialog"> + <title id="tit" xml-lang="en-US">Opening a Dialog with Python</title> + <filename>/text/sbasic/python/python_dialogs.xhp</filename> + </topic> + </meta> + <body> + <bookmark branch="index" id="N0334"> + <bookmark_value>Python;dialogs</bookmark_value> + <bookmark_value>dialog box;Python</bookmark_value> + <bookmark_value>dialogs;Python</bookmark_value> + </bookmark> + <section id="pythondialog1"> + <h1 id="N0336"><variable id="pythondialog"><link href="text/sbasic/python/python_dialogs.xhp" name="command_name">Opening a Dialog with Python</link></variable></h1> + </section> + <paragraph role="paragraph" id="N0337">%PRODUCTNAME static dialogs are created with the <link href="text/sbasic/guide/create_dialog.xhp" name="dialog editor">Dialog editor</link> and are stored in varying places according to their personal (My Macros), shared (%PRODUCTNAME Macros) or document-embedded nature. In reverse, dynamic dialogs are constructed at runtime, from Basic or Python scripts, or using any other <link href="text/shared/guide/scripting.xhp">%PRODUCTNAME supported language</link> for that matter. Opening static dialogs with Python is illustrated herewith. Exception handling and internationalization are omitted for clarity.</paragraph> + <h2 id="N0338">My Macros or %PRODUCTNAME Macros dialogs</h2> + <paragraph role="paragraph" id="N0339">The examples below open <literal>Access2Base Trace</literal> console or the imported <literal>TutorialsDialog</literal> dialog with <menuitem>Tools – Macros – Run Macro...</menuitem> menu:</paragraph> + <pycode> + <paragraph role="pycode" id="N0340" localize="false"># -*- coding: utf-8 -*-</paragraph> + <paragraph role="pycode" id="N0341" localize="false">from __future__ import unicode_literals</paragraph> + <paragraph role="pycode" id="N0342" localize="false"> </paragraph> + <paragraph role="pycode" id="N0343" localize="false">def consoleDlg():</paragraph> + <paragraph role="pycode" id="N0344" localize="false"> ctx =XSCRIPTCONTEXT.getComponentContext()</paragraph> + <paragraph role="pycode" id="N0345" localize="false"> smgr = ctx.getServiceManager()</paragraph> + <paragraph role="pycode" id="N0346" localize="false"> dp = smgr.createInstanceWithContext("com.sun.star.awt.DialogProvider", ctx)</paragraph> + <paragraph role="pycode" id="N0348" localize="false"> dlg = dp.createDialog( "vnd.sun.star.script:Access2Base.dlgTrace?location=application")</paragraph> + <paragraph role="pycode" id="N0350" localize="false"> dlg.execute()</paragraph> + <paragraph role="pycode" id="N0351" localize="false"> dlg.dispose()</paragraph> + <paragraph role="pycode" id="N0352" localize="false"> </paragraph> + <paragraph role="pycode" id="N0353" localize="false">def tutorDialog():</paragraph> + <paragraph role="pycode" id="N0354" localize="false"> ctx =XSCRIPTCONTEXT.getComponentContext()</paragraph> + <paragraph role="pycode" id="N0355" localize="false"> smgr = ctx.getServiceManager()</paragraph> + <paragraph role="pycode" id="N0356" localize="false"> dp = smgr.createInstanceWithContext("com.sun.star.awt.DialogProvider", ctx)</paragraph> + <paragraph role="pycode" id="N0358" localize="false"> dlg = dp.createDialog("vnd.sun.star.script:Standard.TutorialsDialog?location=application")</paragraph> + <paragraph role="pycode" id="N0360" localize="false"> dlg.execute()</paragraph> + <paragraph role="pycode" id="N0361" localize="false"> dlg.dispose()</paragraph> + <paragraph role="pycode" id="N0362" localize="false"> </paragraph> + <paragraph role="pycode" id="N0363" localize="false">g_exportedScripts = (consoleDlg, tutorDialog)</paragraph> + </pycode> + <h2 id="N0364">Document embedded dialogs</h2> + <paragraph role="paragraph" id="N0365">The example below opens a newly edited <literal>Dialog1</literal> dialog from a document with <menuitem>Tools – Macros – Run Macro...</menuitem> menu:</paragraph> + <pycode> + <paragraph role="pycode" id="N0366" localize="false"># -*- coding: utf-8 -*-</paragraph> + <paragraph role="pycode" id="N0367" localize="false">from __future__ import unicode_literals</paragraph> + <paragraph role="pycode" id="N0368" localize="false"> </paragraph> + <paragraph role="pycode" id="N0369" localize="false">def docDialog():</paragraph> + <paragraph role="pycode" id="N0370"> """ Display a doc-based dialog """</paragraph> + <paragraph role="pycode" id="N0371" localize="false"> model = XSCRIPTCONTEXT.getDocument()</paragraph> + <paragraph role="pycode" id="N0372" localize="false"> smgr = XSCRIPTCONTEXT.getComponentContext().ServiceManager</paragraph> + <paragraph role="pycode" id="N0373" localize="false"> dp = smgr.createInstanceWithArguments( "com.sun.star.awt.DialogProvider", (model,))</paragraph> + <paragraph role="pycode" id="N0375" localize="false"> dlg = dp.createDialog( "vnd.sun.star.script:Standard.Dialog1?location=document")</paragraph> + <paragraph role="pycode" id="N0377" localize="false"> dlg.execute()</paragraph> + <paragraph role="pycode" id="N0378" localize="false"> dlg.dispose()</paragraph> + <paragraph role="pycode" id="N0379" localize="false"> </paragraph> + <paragraph role="pycode" id="N0380" localize="false">g_exportedScripts = (docDialog,)</paragraph> + </pycode> + <paragraph role="paragraph" id="N0381">Refer to <literal>msgbox.py</literal> in <literal>{installation}/program/</literal> directory for Python dynamic dialog examples.</paragraph> + <section id="relatedtopics" > + <embed href="text/sbasic/guide/show_dialog.xhp#show_dialog"/> + <embed href="text/sbasic/python/python_examples.xhp#pythonexamples2"/> + <embed href="text/sbasic/python/main0000.xhp#pythonscriptshelp"/> + </section> +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/python/python_document_events.xhp b/helpcontent2/source/text/sbasic/python/python_document_events.xhp new file mode 100644 index 000000000..34a3f5a5b --- /dev/null +++ b/helpcontent2/source/text/sbasic/python/python_document_events.xhp @@ -0,0 +1,276 @@ +<?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="text/sbasic/python/python_document_events"> + <title id="tit" xml-lang="en-US">Python : Monitoring Document Events</title> + <filename>/text/sbasic/python/python_document_events.xhp</filename> + </topic> + </meta> + <body> + <bookmark branch="index" id="N0526"> + <bookmark_value>Basic;Monitoring Document Events</bookmark_value> + <bookmark_value>Python;Monitoring Document Events</bookmark_value> + <bookmark_value>Access2Base;Console</bookmark_value> + <bookmark_value>Access2Base;Trace</bookmark_value> + <bookmark_value>Tools;Strings</bookmark_value> + <bookmark_value>API;GlobalScope.BasicLibraries</bookmark_value> + <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.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> + <bookmark_value>API;script.provider.XScript: Monitoring Document Event</bookmark_value> + </bookmark> + <section id="pythonmonitor1"> + <h1 id="N0527"><variable id="pythonmonitor"><link href="text/sbasic/python/python_document_events.xhp" name="Monitoring Document Events">Monitoring Document Events</link></variable></h1> + </section> + <paragraph role="paragraph" id="N0528">Next to <link href="text/sbasic/shared/01040000.xhp" name ="assigning macros to events">assigning macros to events</link>, one can monitor events raised by %PRODUCTNAME documents. Application Programming Interface (API) broadcasters are responsible for calling event scripts. Unlike listeners that require to define all supported methods, even if unused, document monitors require only two methods next to hooked event scripts.</paragraph> + <h2 id="N0529">Listening to Document Events</h2> + <paragraph role="paragraph" id="N0530">Monitoring is illustrated herewith for Basic and Python languages using object-oriented programming. Assigning <literal>OnLoad</literal> script, to the <literal>Open Document</literal> event, suffices to initiate and terminate document event monitoring. <menuitem>Tools – Customise...</menuitem> menu <menuitem>Events</menuitem> tab is used to assign either scripts.</paragraph> + <paragraph role="paragraph" id="N0531">Intercepting events helps setting scripts pre- and post-conditions such as loading and unloading libraries or track script processing in the background. <literal>Access2Base Trace</literal> module usage is illustrating that second context.</paragraph> + <h3 id="N0532">With Python</h3> + <paragraph role="paragraph" id="N0533">Events monitoring starts from object instantiation and ultimately stops when Python releases the object. Raised events are reported using <literal>Access2Base</literal> console.</paragraph> + <note id="N0534"><literal>OnLoad</literal> and <literal>OnUnload</literal> events can be used to respectively set and unset Python programs path. They are described as <literal>Open document</literal> and <literal>Document closed</literal>.</note> + <pycode> + <paragraph role="pycode" localize="false" id="N0535"># -*- coding: utf-8 -*-</paragraph> + <paragraph role="pycode" localize="false" id="N0536">from __future__ import unicode_literals</paragraph> + <paragraph role="pycode" localize="false" id="N0537"> </paragraph> + <paragraph role="pycode" localize="false" id="N0538">import os.path, uno, unohelper</paragraph> + <paragraph role="pycode" localize="false" id="N0539">from com.sun.star.document import DocumentEvent, \</paragraph> + <paragraph role="pycode" localize="false" id="N0540"> XDocumentEventListener as AdapterPattern</paragraph> + <paragraph role="pycode" localize="false" id="N0541">from com.sun.star.lang import EventObject</paragraph> + <paragraph role="pycode" localize="false" id="N0542"> </paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0543">class UiDocument(unohelper.Base, AdapterPattern):</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0544"> """ Monitor document events """</paragraph> + <paragraph role="pycode" localize="false" id="N0545"> '''</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0546"> adapted from 'Python script to monitor OnSave event' at</paragraph> + <paragraph role="pycode" localize="false" id="N0547"> https://forum.openoffice.org/en/forum/viewtopic.php?t=68887</paragraph> + <paragraph role="pycode" localize="false" id="N0548"> '''</paragraph> + <paragraph role="pycode" localize="false" id="N0549"> def __init__(self):</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0550"> """ Document events monitor """</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0551"> ''' report using Access2Base.Trace console OR</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0552"> report in 1st sheet, 1st column for Calc docs '''</paragraph> + <paragraph role="pycode" localize="false" id="N0553"> ctx = uno.getComponentContext()</paragraph> + <paragraph role="pycode" localize="false" id="N0554"> smgr = ctx.getServiceManager()</paragraph> + <paragraph role="pycode" localize="false" id="N0555"> desktop = smgr.createInstanceWithContext(</paragraph> + <paragraph role="pycode" localize="false" id="N0556"> 'com.sun.star.frame.Desktop' , ctx)</paragraph> + <paragraph role="pycode" localize="false" id="N0557"> self.doc = desktop.CurrentComponent</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0558"> #self.row = 0 # uncomment for Calc documents only</paragraph> + <paragraph role="pycode" localize="false" id="N0559"> Console.setLevel("DEBUG")</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0560"> self.listen() # Start monitoring doc. events</paragraph> + <paragraph role="pycode" localize="false" id="N0562"> </paragraph> + <paragraph role="pycode" localize="false" id="N0563"> @property</paragraph> + <paragraph role="pycode" localize="false" id="N0564"> def Filename(self) -> str:</paragraph> + <paragraph role="pycode" localize="false" id="N0565"> sys_filename = uno.fileUrlToSystemPath(self.doc.URL)</paragraph> + <paragraph role="pycode" localize="false" id="N0566"> return os.path.basename(sys_filename)</paragraph> + <paragraph role="pycode" localize="false" id="N0567"> </paragraph> + <paragraph role="pycode" localize="false" id="N0568"> def setCell(self, calcDoc, txt: str):</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0569"> """ Output doc. events on 1st column of a Calc spreadsheet """</paragraph> + <paragraph role="pycode" localize="false" id="N0570"> sheet = calcDoc.getSheets().getByIndex(0)</paragraph> + <paragraph role="pycode" localize="false" id="N0571"> sheet.getCellByPosition(0,self.row).setString(txt)</paragraph> + <paragraph role="pycode" localize="false" id="N0572"> self.row = self.row + 1</paragraph> + <paragraph role="pycode" localize="false" id="N0574"> </paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0575"> def listen(self, *args): # OnLoad/OnNew at the earliest</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0576"> """ Start doc. events monitoring """</paragraph> + <paragraph role="pycode" localize="false" id="N0577"> self.doc.addDocumentEventListener(self)</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0578"> Console.log("INFO", "Document events are being logged", True)</paragraph> + <paragraph role="pycode" localize="false" id="N0579"> </paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0580"> def sleep(self, *args): # OnUnload at the latest (optional)</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0581"> """ Stop doc. events monitoring """</paragraph> + <paragraph role="pycode" localize="false" id="N0582"> self.doc.removeDocumentEventListener(self)</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0583"> Console.log("INFO", "Document events have been logged", True)</paragraph> + <paragraph role="pycode" localize="false" id="N0585"> </paragraph> + <paragraph role="pycode" localize="false" id="N0586"> def documentEventOccured(self, event: DocumentEvent):</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0587"> """ Intercepts all doc. events """</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0588"> #self.setCell(event.Source, event.EventName) # only for Calc docs</paragraph> + <paragraph role="pycode" localize="false" id="N0589"> Console.log("DEBUG",</paragraph> + <paragraph role="pycode" localize="false" id="N0590"> event.EventName+" in "+self.Filename,</paragraph> + <paragraph role="pycode" localize="false" id="N0591"> False)</paragraph> + <paragraph role="pycode" localize="false" id="N0593"> </paragraph> + <paragraph role="pycode" localize="false" id="N0594"> def disposing(self, event: EventObject):</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0595"> """ Release all activities """</paragraph> + <paragraph role="pycode" localize="false" id="N0596"> self.sleep()</paragraph> + <paragraph role="pycode" localize="false" id="N0597"> Console.show()</paragraph> + <paragraph role="pycode" localize="false" id="N0599"> </paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0601">def OnLoad(*args): # 'Open Document' event</paragraph> + <paragraph role="pycode" localize="false" id="N0602"> listener = UiDocument() # Initiates listening</paragraph> + <paragraph role="pycode" localize="false" id="N0603"> </paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0604">def OnUnload(*args): # 'Document has been closed' event</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0605"> pass # (optional) performed when disposed</paragraph> + <paragraph role="pycode" localize="false" id="N0606"> </paragraph> + <paragraph role="pycode" localize="false" id="N0607">g_exportedScripts = (OnLoad,)</paragraph> + <paragraph role="pycode" localize="false" id="N0609"> </paragraph> + <paragraph role="pycode" localize="false" id="N0610">from com.sun.star.script.provider import XScript</paragraph> + <paragraph role="pycode" localize="false" id="N0611">class Console():</paragraph> + <paragraph role="pycode" localize="false" id="N0612"> """</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0613"> (Back/Fore)ground console to report/log program execution.</paragraph> + <paragraph role="pycode" localize="false" id="N0614"> """</paragraph> + <paragraph role="pycode" localize="false" id="N0615"> @staticmethod</paragraph> + <paragraph role="pycode" localize="false" id="N0616"> def trace(*args,**kwargs):</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0617"> """ Print free item list to console """</paragraph> + <paragraph role="pycode" localize="false" id="N0618"> scr = Console._a2bScript(script='DebugPrint', module='Compatible')</paragraph> + <paragraph role="pycode" localize="false" id="N0619"> scr.invoke((args),(),())</paragraph> + <paragraph role="pycode" localize="false" id="N0620"> @staticmethod</paragraph> + <paragraph role="pycode" localize="false" id="N0621"> def log(level: str, text: str, msgBox=False):</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0622"> """ Append log message to console, optional user prompt """</paragraph> + <paragraph role="pycode" localize="false" id="N0623"> scr = Console._a2bScript(script='TraceLog')</paragraph> + <paragraph role="pycode" localize="false" id="N0624"> scr.invoke((level,text,msgBox),(),())</paragraph> + <paragraph role="pycode" localize="false" id="N0625"> @staticmethod</paragraph> + <paragraph role="pycode" localize="false" id="N0626"> def setLevel(logLevel: str):</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0627"> """ Set log messages lower limit """</paragraph> + <paragraph role="pycode" localize="false" id="N0628"> scr = Console._a2bScript(script='TraceLevel')</paragraph> + <paragraph role="pycode" localize="false" id="N0629"> scr.invoke((logLevel,),(),())</paragraph> + <paragraph role="pycode" localize="false" id="N0630"> @staticmethod</paragraph> + <paragraph role="pycode" localize="false" id="N0631"> def show():</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0632"> """ Display console content/dialog """</paragraph> + <paragraph role="pycode" localize="false" id="N0633"> scr = Console._a2bScript(script='TraceConsole')</paragraph> + <paragraph role="pycode" localize="false" id="N0634"> scr.invoke((),(),())</paragraph> + <paragraph role="pycode" localize="false" id="N0635"> @staticmethod</paragraph> + <paragraph role="pycode" localize="false" id="N0636"> def _a2bScript(script: str, library='Access2Base',</paragraph> + <paragraph role="pycode" localize="false" id="N0637"> module='Trace') -> XScript:</paragraph> + <paragraph role="pycode" localize="false" id="N0638"> ''' Grab application-based Basic script '''</paragraph> + <paragraph role="pycode" localize="false" id="N0639"> sm = uno.getComponentContext().ServiceManager</paragraph> + <paragraph role="pycode" localize="false" id="N0640"> mspf = sm.createInstanceWithContext(</paragraph> + <paragraph role="pycode" localize="false" id="N0641"> "com.sun.star.script.provider.MasterScriptProviderFactory",</paragraph> + <paragraph role="pycode" localize="false" id="N0642"> uno.getComponentContext())</paragraph> + <paragraph role="pycode" localize="false" id="N0643"> scriptPro = mspf.createScriptProvider("")</paragraph> + <paragraph role="pycode" localize="false" id="N0644"> scriptName = "vnd.sun.star.script:"+library+"."+module+"."+script+"?language=Basic&location=application"</paragraph> + <paragraph role="pycode" localize="false" id="N0645"> xScript = scriptPro.getScript(scriptName)</paragraph> + <paragraph role="pycode" localize="false" id="N0646"> return xScript</paragraph> + </pycode> + <warning id="N0647">Mind the misspelled <literal>documentEventOccured</literal> method that inherits a typo from %PRODUCTNAME Application Programming Interface (API).</warning> + <paragraph role="tip" id="N0648"><literal>Start application</literal> and <literal>Close application</literal> events can respectively be used to set and to unset Python path for user scripts or %PRODUCTNAME scripts. In a similar fashion, document based Python libraries or modules can be loaded and released using <literal>Open document</literal> and <literal>Document closed</literal> events. Refer to <link href="text/sbasic/python/python_import.xhp" name ="Importing Python Modules">Importing Python Modules</link> for more information.</paragraph> + <h3 id="N0649">With %PRODUCTNAME Basic</h3> + <paragraph role="paragraph" id="N0650">The <literal>Onload</literal> script is assigned to <literal>Open document</literal> event using <menuitem>Tools – Customise...</menuitem> menu <menuitem>Events</menuitem> tab. Events monitoring starts from the moment a <literal>ConsoleLogger</literal> object is instantiated and ultimately stops when Basic engine releases it. <literal>OnLoad</literal> event loads necessary Basic libraries, while caught events are reported using <literal>Access2Base.Trace</literal> module.</paragraph> + <bascode> + <paragraph role="bascode" xml-lang="en-US" id="N0651">REM controller.Events module</paragraph> + <paragraph role="bascode" localize="false" id="N0652">Option Explicit</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0653">Private _obj As Object ' controller.ConsoleLogger instance</paragraph> + <paragraph role="bascode" localize="false" id="N0654"> </paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0655">Sub OnLoad(evt As com.sun.star.document.DocumentEvent) ' >> Open Document <<</paragraph> + <paragraph role="bascode" localize="false" id="N0656"> _obj = New ConsoleLogger : _obj.Start(evt)</paragraph> + <paragraph role="bascode" localize="false" id="N0657">End Sub ' controller.OnLoad</paragraph> + <paragraph role="bascode" localize="false" id="N0658">' ----</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0659">REM controller.ConsoleLogger class module</paragraph> + <paragraph role="bascode" localize="false" id="N0660">Option Explicit</paragraph> + <paragraph role="bascode" localize="false" id="N0661">Option Compatible</paragraph> + <paragraph role="bascode" localize="false" id="N0662">Option ClassModule</paragraph> + <paragraph role="bascode" localize="false" id="N0663"> </paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0664">' ADAPTER design pattern object to be instantiated in « Open Document » event</paragraph> + <paragraph role="bascode" localize="false" id="N0665">Private Const UI_PROMPT = True</paragraph> + <paragraph role="bascode" localize="false" id="N0666">Private Const UI_NOPROMPT = False ' Set it to True to visualise documents events</paragraph> + <paragraph role="bascode" localize="false" id="N0667"> </paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0668">' CONSTRUCTOR/DESTRUCTOR</paragraph> + <paragraph role="bascode" localize="false" id="N0669">Private Sub Class_Initialize()</paragraph> + <paragraph role="bascode" localize="false" id="N0670">End Sub ' controller.ConsoleLogger.Initialize</paragraph> + <paragraph role="bascode" localize="false" id="N0671">Private Sub Class_Terminate()</paragraph> + <paragraph role="bascode" localize="false" id="N0672">End Sub ' controller.ConsoleLogger.Terminate</paragraph> + <paragraph role="bascode" localize="false" id="N0673"> </paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0674">' MEMBERS</paragraph> + <paragraph role="bascode" localize="false" id="N0675">Private _evtAdapter As Object ' com.sun.star.document.XDocumentEventBroadcaster</paragraph> + <paragraph role="bascode" localize="false" id="N0676"> </paragraph> + <paragraph role="bascode" localize="false" id="N0677">' PROPERTIES</paragraph> + <paragraph role="bascode" localize="false" id="N0678">Private Property Get FileName As String</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0679"> ''' System-dependent filename '''</paragraph> + <paragraph role="bascode" localize="false" id="N0680"> Const _LIBRARY = "Tools" : With GlobalScope.BasicLibraries</paragraph> + <paragraph role="bascode" localize="false" id="N0681"> If Not .IsLibraryLoaded(_LIBRARY) Then .LoadLibrary(_LIBRARY)</paragraph> + <paragraph role="bascode" localize="false" id="N0682"> End With</paragraph> + <paragraph role="bascode" localize="false" id="N0683"> Filename = Tools.Strings.FilenameOutofPath(ThisComponent.URL)</paragraph> + <paragraph role="bascode" localize="false" id="N0684">End Property ' controller.ConsoleLogger.Filename</paragraph> + <paragraph role="bascode" localize="false" id="N0685"> </paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0686">' METHODS</paragraph> + <paragraph role="bascode" localize="false" id="N0687">Private Sub _documentEventOccured(evt As com.sun.star.document.DocumentEvent)</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0688"> ''' Monitor document events '''</paragraph> + <paragraph role="bascode" localize="false" id="N0689"> Access2Base.Trace.TraceLog("DEBUG", _</paragraph> + <paragraph role="bascode" localize="false" id="N0690"> evt.EventName &" in "& Filename(evt.Source.URL), _</paragraph> + <paragraph role="bascode" localize="false" id="N0691"> UI_NOPROMPT)</paragraph> + <paragraph role="bascode" localize="false" id="N0692"> Select Case evt.EventName</paragraph> + <paragraph role="bascode" localize="false" id="N0693"> Case "OnUnload" : _Stop(evt)</paragraph> + <paragraph role="bascode" localize="false" id="N0694"> End Select</paragraph> + <paragraph role="bascode" localize="false" id="N0695">End Sub ' controller.ConsoleLogger._documentEventOccured</paragraph> + <paragraph role="bascode" localize="false" id="N0696"> </paragraph> + <paragraph role="bascode" localize="false" id="N0697">Private Sub _disposing(evt As com.sun.star.lang.EventObject)</paragraph> + <paragraph role="bascode" localize="false" id="N0698">End Sub ' controller.ConsoleLogger.disposing</paragraph> + <paragraph role="bascode" localize="false" id="N0699"> </paragraph> + <paragraph role="bascode" localize="false" id="N0700">Public Sub Start(Optional evt As com.sun.star.document.DocumentEvent)</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0701"> ''' Initialize document events logging '''</paragraph> + <paragraph role="bascode" localize="false" id="N0702"> Const _LIBRARY = "Access2Base" : With GlobalScope.BasicLibraries</paragraph> + <paragraph role="bascode" localize="false" id="N0703"> If Not .IsLibraryLoaded(_LIBRARY) Then .LoadLibrary(_LIBRARY)</paragraph> + <paragraph role="bascode" localize="false" id="N0704"> End With : Access2Base.Trace.TraceLevel("DEBUG")</paragraph> + <paragraph role="bascode" localize="false" id="N0705"> Access2Base.Trace.TraceLog("INFO", _</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0706"> IIf(IsMissing(evt),"",evt.EventName & "-") & "Document events are being logged", _</paragraph> + <paragraph role="bascode" localize="false" id="N0707"> UI_PROMPT)</paragraph> + <paragraph role="bascode" localize="false" id="N0708"> </paragraph> + <paragraph role="bascode" localize="false" id="N0709"> _evtAdapter = CreateUnoListener( "_", "com.sun.star.document.XDocumentEventListener" )</paragraph> + <paragraph role="bascode" localize="false" id="N0710"> ThisComponent.addDocumentEventListener( _evtAdapter )</paragraph> + <paragraph role="bascode" localize="false" id="N0711">End Sub ' controller.ConsoleLogger.Start</paragraph> + <paragraph role="bascode" localize="false" id="N0712"> </paragraph> + <paragraph role="bascode" localize="false" id="N0713">Private Sub _Stop(Optional evt As com.sun.star.document.DocumentEvent)</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0714"> ''' Terminate document events logging '''</paragraph> + <paragraph role="bascode" localize="false" id="N0715"> ThisComponent.removeDocumentEventListener( _evtAdapter )</paragraph> + <paragraph role="bascode" localize="false" id="N0716"> Access2Base.Trace.TraceLog("INFO", _</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0717"> IIf(IsMissing(evt),"",evt.EventName & "-") & "Document events have been logged", _</paragraph> + <paragraph role="bascode" localize="false" id="N0718"> UI_PROMPT)</paragraph> + <paragraph role="bascode" localize="false" id="N0719"> Access2Base.Trace.TraceConsole() ' Captured events dialog</paragraph> + <paragraph role="bascode" localize="false" id="N0720">End Sub ' controller.ConsoleLogger._Stop</paragraph> + <paragraph role="bascode" localize="false" id="N0721"> </paragraph> + <paragraph role="bascode" localize="false" id="N0722">' EVENTS</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0723">' Your code for handled events goes here</paragraph> + </bascode> + <warning id="N0724">Mind the misspelled <literal>_documentEventOccured</literal> method that inherits a typo from %PRODUCTNAME Application Programming Interface (API).</warning> + <h2 id="N0725">Discovering Documents Events</h2> + <paragraph role="paragraph" id="N0726">The broadcaster API object provides the list of events it is responsible for:</paragraph> + <h3 id="N0727">With Python</h3> + <pycode> + <paragraph role="pycode" localize="false" id="N0728"># -*- coding: utf-8 -*-</paragraph> + <paragraph role="pycode" localize="false" id="N0729">from __future__ import unicode_literals</paragraph> + <paragraph role="pycode" localize="false" id="N0730"> </paragraph> + <paragraph role="pycode" localize="false" id="N0731">import uno, apso_utils as ui</paragraph> + <paragraph role="pycode" localize="false" id="N0732"> </paragraph> + <paragraph role="pycode" localize="false" id="N0733">def displayAvailableEvents():</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0734"> """ Display document events """</paragraph> + <paragraph role="pycode" localize="false" id="N0735"> '''</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0736"> adapted from DisplayAvailableEvents() by A. Pitonyak</paragraph> + <paragraph role="pycode" localize="false" id="N0737"> https://forum.openoffice.org/en/forum/viewtopic.php?&t=43689</paragraph> + <paragraph role="pycode" localize="false" id="N0738"> '''</paragraph> + <paragraph role="pycode" localize="false" id="N0739"> ctx = XSCRIPTCONTEXT.getComponentContext()</paragraph> + <paragraph role="pycode" localize="false" id="N0740"> smgr = ctx.ServiceManager</paragraph> + <paragraph role="pycode" localize="false" id="N0741"> geb = smgr.createInstanceWithContext(</paragraph> + <paragraph role="pycode" localize="false" id="N0742"> "com.sun.star.frame.GlobalEventBroadcaster", ctx)</paragraph> + <paragraph role="pycode" localize="false" id="N0743"> events = geb.Events.getElementNames()</paragraph> + <paragraph role="pycode" localize="false" id="N0744"> ui.msgbox('; '.join(events))</paragraph> + <paragraph role="pycode" localize="false" id="N0745"> </paragraph> + <paragraph role="pycode" localize="false" id="N0746">g_exportedScripts = (displayAvailableEvents,)</paragraph> + </pycode> + <note id="N0747">The <link href="https://extensions.libreoffice.org/extensions/apso-alternative-script-organizer-for-python" name ="Alternative Python Script Organizer">Alternative Python Script Organizer (APSO)</link> extension is used to render events information on screen.</note> + <h3 id="N0748">With %PRODUCTNAME Basic</h3> + <bascode> + <paragraph role="bascode" localize="false" id="N0749">Sub DisplayAvailableEvents</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0750"> ''' Display document events '''</paragraph> + <paragraph role="bascode" localize="false" id="N0751"> Dim geb As Object ' com.sun.star.frame.GlobalEventBroadcaster</paragraph> + <paragraph role="bascode" localize="false" id="N0752"> Dim events() As String</paragraph> + <paragraph role="bascode" localize="false" id="N0753"> geb = CreateUnoService("com.sun.star.frame.GlobalEventBroadcaster")</paragraph> + <paragraph role="bascode" localize="false" id="N0754"> events = geb.Events.ElementNames()</paragraph> + <paragraph role="bascode" localize="false" id="N0755"> MsgBox Join(events, "; ")</paragraph> + <paragraph role="bascode" localize="false" id="N0756">End Sub</paragraph> + </bascode> + <section id="relatedtopics" > + <embed href="text/sbasic/python/python_listener.xhp#pythonlistener"/> + <embed href="text/sbasic/python/python_import.xhp#pythonimporth1"/> + <embed href="text/sbasic/python/python_handler.xhp#pythonhandler_h1"/> + <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/helpcontent2/source/text/sbasic/python/python_examples.xhp b/helpcontent2/source/text/sbasic/python/python_examples.xhp new file mode 100644 index 000000000..c5b496ed0 --- /dev/null +++ b/helpcontent2/source/text/sbasic/python/python_examples.xhp @@ -0,0 +1,42 @@ +<?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="pythonexamples" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">Python examples</title> + <filename>/text/sbasic/python/python_examples.xhp</filename> + </topic> + </meta> + <body> + <section id="pythonexamples"> + <bookmark xml-lang="en-US" branch="index" id="bm_id20191031405"> + <bookmark_value>Python;examples</bookmark_value> + <bookmark_value>Python;shell</bookmark_value> + <bookmark_value>Python;platform</bookmark_value> + <bookmark_value>Python;session</bookmark_value> + <bookmark_value>Python;screen input/output</bookmark_value> + </bookmark> + <h1 id="hd_id201901031407"><variable id="pythonexamples2"><link href="text/sbasic/python/python_examples.xhp" name="python examples">Python programming examples</link></variable></h1> + </section> + <embed href="text/sbasic/python/python_session.xhp#pythonsession"/> + <embed href="text/sbasic/python/python_platform.xhp#pythonplatform"/> + <embed href="text/sbasic/python/python_import.xhp#pythonimporth1"/> + <embed href="text/sbasic/python/python_screen.xhp#ioscreen"/> + <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_handler.xhp#pythonhandler_h1"/> + <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/guide/basic_2_python.xhp#basic2python"/> + <embed href="text/sbasic/python/main0000.xhp#pythonscriptshelp"/> + </section> +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/python/python_handler.xhp b/helpcontent2/source/text/sbasic/python/python_handler.xhp new file mode 100644 index 000000000..87887105e --- /dev/null +++ b/helpcontent2/source/text/sbasic/python/python_handler.xhp @@ -0,0 +1,169 @@ +<?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="text/sbasic/python/python_handler"> + <title id="tit" xml-lang="en-US">Creating A Dialog Handler</title> + <filename>/text/sbasic/python/python_handler.xhp</filename> + </topic> + </meta> + <body> + <bookmark branch="index" id="N0664"> + <bookmark_value>Basic;Dialog Handler</bookmark_value> + <bookmark_value>Python;Dialog Handler</bookmark_value> + <bookmark_value>Access2Base;dlgTrace</bookmark_value> + <bookmark_value>Access2Base;_DumpToFile</bookmark_value> + <bookmark_value>API;DialogProvider2</bookmark_value> + <bookmark_value>API;XDialogEventHandler</bookmark_value> + </bookmark> + <bookmark xml-lang="en-US" branch="hid/cui/ui/assigncomponentdialog/AssignComponent" id="bm_id66701251" localize="false"/> + <h1 id="N0665"><variable id="pythonhandler_h1"><link href="text/sbasic/python/python_handler.xhp" name="Creating a Dialog Handler">Creating a Dialog Handler</link></variable></h1> + <paragraph role="paragraph" id="N0666">Next to <link href="text/sbasic/shared/01040000.xhp" name ="Assigning macros to events">assigning macros to events</link> or <link href="text/sbasic/basic/python/python_listener" name ="creating event listeners">creating event listeners</link>, one can use dialog handlers, whose principle is to define UNO keywords, or methods, that are mapped to events to watch for. The event handler is responsible for executing methods using the <literal>vnd.sun.star.UNO:<method_name></literal> protocol. Unlike listeners that require to define all supported methods, even if unused, dialog handlers require only two methods on top of intended control hook scripts.</paragraph> + <paragraph role="paragraph" id="N0667">The advantages of this approach are:</paragraph> + <list type="unordered"> + <listitem><paragraph role="listitem" id="N0668">It packs the code that handles event-driven macros,</paragraph></listitem> + <listitem><paragraph role="listitem" id="N0669">it decorrelates events from macros names which facilitates maintenance or updates, in particular when moving macros or modules.</paragraph></listitem> + </list> + <paragraph role="paragraph" id="N0670">This mechanism is illustrated herewith for Basic and Python languages using an imported copy of <literal>Access2Base</literal> <literal>dlgTrace</literal> dialog. Exception handling and localisation are omitted for clarity.</paragraph> + <h2 id="N0671">Assigning Dialog methods</h2> + <paragraph role="paragraph" id="N0672">Export <literal>Access2Base</literal> <literal>dlgTrace</literal> dialog and import it into <literal>MyLib</literal> application library.</paragraph> + <paragraph role="paragraph" id="N0673">Inside the control properties pane of the <link href="text/sbasic/guide/create_dialog.xhp" name ="Dialog Editor">Dialog Editor</link>, use the Events tab to replace macro assignments by component assignments, and type in the intended method names:</paragraph> + <list type="unordered"> + <listitem><paragraph role="listitem" id="N0674">Set <literal>Dump to file</literal> dialog button component method name to <literal>_dump2File</literal></paragraph></listitem> + <listitem><paragraph role="listitem" id="N0675">Optionally define <literal>txtTracelog</literal> key pressed and mouse button pressed events component method names as <literal>_openHelp</literal></paragraph></listitem> + <listitem><paragraph role="listitem" id="N0676">Optionally define <literal>Ok</literal> button receiving focus event component method name as <literal>onOkHasfocus</literal></paragraph></listitem> + </list> + <paragraph role="paragraph" id="N0677">Events assigned actions should mention the <literal>vnd.sun.star.UNO:</literal> protocol.</paragraph> + <h2 id="N0678">Creating the handler</h2> + <paragraph role="paragraph" id="N0679"><literal>createDialogWithHandler</literal> method of <link href="https://api.libreoffice.org/docs/idl/ref/servicecom_1_1sun_1_1star_1_1awt_1_1DialogProvider2.html" name ="com.sun.star.awt.DialogProvider2">com.sun.star.awt.DialogProvider2</link> service is used to set the dialog and its handler. The handler is responsible for implementing <link href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1awt_1_1XDialogEventHandler.html" name ="com.sun.star.awt.XDialogEventHandler">com.sun.star.awt.XDialogEventHandler</link> interface.</paragraph> + <warning id="N0680">All component method names must be explicitly declared when using a dialog handler.</warning> + <h3 id="N0681">With Python</h3> + <paragraph role="paragraph" id="N0682">In this example the dialog is located on the computer.</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="N0683"># -*- coding: utf-8 -*-</paragraph> + <paragraph role="pycode" localize="false" id="N0684">from __future__ import unicode_literals</paragraph> + <paragraph role="pycode" localize="false" id="N0685"> </paragraph> + <paragraph role="pycode" localize="false" id="N0686">import uno, unohelper</paragraph> + <paragraph role="pycode" localize="false" id="N0687">from com.sun.star.awt import XDialogEventHandler</paragraph> + <paragraph role="pycode" localize="false" id="N0688"> </paragraph> + <paragraph role="pycode" localize="false" id="N0689">_DLG_PROVIDER = "com.sun.star.awt.DialogProvider2"</paragraph> + <paragraph role="pycode" localize="false" id="N0690"> </paragraph> + <paragraph role="pycode" localize="false" id="N0691">class Console(unohelper.Base, XDialogEventHandler):</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0692"> """ Access2Base Console Handler """</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0693"> ''' adapted from « Créer un dialogue avec gestionnaire d'événements » by JM Zambon</paragraph> + <paragraph role="pycode" localize="false" id="N0694"> https://wiki.openoffice.org/wiki/FR/Documentation/Python/Creating_Dialog_with_Handler '''</paragraph> + <paragraph role="pycode" localize="false" id="N0695"> def show(self):</paragraph> + <paragraph role="pycode" localize="false" id="N0696"> dialog = self.getDialog("MyLib.dlgTrace", embedded=True)</paragraph> + <paragraph role="pycode" localize="false" id="N0697"> dialog.Title = "Konsole"</paragraph> + <paragraph role="pycode" localize="false" id="N0698"> dialog.execute()</paragraph> + <paragraph role="pycode" localize="false" id="N0699"> </paragraph> + <paragraph role="pycode" localize="false" id="N0700"> def callHandlerMethod(self, dialog, event, method):</paragraph> + <paragraph role="pycode" localize="false" id="N0701"> if method == '_dump2File':</paragraph> + <paragraph role="pycode" localize="false" id="N0702"> event.Source.setLabel("dump requested")</paragraph> + <paragraph role="pycode" localize="false" id="N0703"> scr = getBasicScript(script="_DumpToFile", module="Trace",</paragraph> + <paragraph role="pycode" localize="false" id="N0704"> library='Access2Base')</paragraph> + <paragraph role="pycode" localize="false" id="N0705"> scr.invoke((event,), (), ())</paragraph> + <paragraph role="pycode" localize="false" id="N0706"> elif method == '_openHelp':</paragraph> + <paragraph role="pycode" localize="false" id="N0707"> _msgbox('Not yet implemented')</paragraph> + <paragraph role="pycode" localize="false" id="N0708"> dialog.endDialog(1)</paragraph> + <paragraph role="pycode" localize="false" id="N0709"> else:</paragraph> + <paragraph role="pycode" localize="false" id="N0710"> return False</paragraph> + <paragraph role="pycode" localize="false" id="N0711"> </paragraph> + <paragraph role="pycode" localize="false" id="N0712"> def getSupportedMethodNames(self):</paragraph> + <paragraph role="pycode" localize="false" id="N0713"> return ('_dump2File', '_openHelp')</paragraph> + <paragraph role="pycode" localize="false" id="N0714"> </paragraph> + <paragraph role="pycode" localize="false" id="N0715"> def getDialog(self, libr_dlg: str, embedded=False):</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0716"> """ Create a Dialog from its location """</paragraph> + <paragraph role="pycode" localize="false" id="N0717"> smgr = XSCRIPTCONTEXT.getComponentContext().ServiceManager</paragraph> + <paragraph role="pycode" localize="false" id="N0718"> if embedded:</paragraph> + <paragraph role="pycode" localize="false" id="N0719"> model = XSCRIPTCONTEXT.getDocument()</paragraph> + <paragraph role="pycode" localize="false" id="N0720"> dp = smgr.createInstanceWithArguments(_DLG_PROVIDER, (model,))</paragraph> + <paragraph role="pycode" localize="false" id="N0721"> location = "?location=document"</paragraph> + <paragraph role="pycode" localize="false" id="N0722"> else:</paragraph> + <paragraph role="pycode" localize="false" id="N0723"> dp = smgr.createInstanceWithContext(_DLG_PROVIDER, ctx)</paragraph> + <paragraph role="pycode" localize="false" id="N0724"> location = "?location=application"</paragraph> + <paragraph role="pycode" localize="false" id="N0725"> dlg = dp.createDialogWithHandler("vnd.sun.star.script:"+libr_dlg+location, self)</paragraph> + <paragraph role="pycode" localize="false" id="N0726"> return dlg</paragraph> + <paragraph role="pycode" localize="false" id="N072A"> </paragraph> + <!-- WIP need extra work to embed remote code + <embed href="text/sbasic/python/Python_2_Basic.xhp#Python_getBasicScript" /> --> + <paragraph role="pycode" localize="false" id="N072B"># def getBasicScript() # see note</paragraph> + <paragraph role="pycode" localize="false" id="N0727"> </paragraph> + <paragraph role="pycode" localize="false" id="N0728">def _msgbox(prompt='', title=''):</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0729"> ''' Ugly MsgBox '''</paragraph> + <paragraph role="pycode" localize="false" id="N0730"> import msgbox</paragraph> + <paragraph role="pycode" localize="false" id="N0731"> mb = msgbox.MsgBox(uno.getComponentContext())</paragraph> + <paragraph role="pycode" localize="false" id="N0732"> mb.addButton('Howdy')</paragraph> + <paragraph role="pycode" localize="false" id="N0733"> mb.show(prompt,0,title)</paragraph> + <paragraph role="pycode" localize="false" id="N0734"> </paragraph> + <paragraph role="pycode" localize="false" id="N0735">def ConsoleHandler():</paragraph> + <paragraph role="pycode" localize="false" id="N0736"> Console().show()</paragraph> + <paragraph role="pycode" localize="false" id="N0737"> </paragraph> + <paragraph role="pycode" localize="false" id="N0738">g_exportedScripts = (ConsoleHandler,)</paragraph> + <paragraph role="pycode" localize="false" id="N0739"> </paragraph> + </pycode> + <note id="N0740">As expected, <literal>onOkHasFocus</literal> missing method throws an exception.</note> + <tip id="N0741">Refer to <link href="text/sbasic/python/python_2_basic.xhp" name ="Python calls to %PRODUCTNAME Basic">Python calls to %PRODUCTNAME Basic</link> page for <literal>getBasicScript</literal> routine description and for details about cross-language scripting execution.</tip> + <h3 id="N0742">With %PRODUCTNAME Basic</h3> + <paragraph role="paragraph" id="N0743">In this example the dialog is embedded in a document, and can equally be located on the computer.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="N0744">' <MyLib>.<Handler> module</paragraph> + <paragraph role="bascode" localize="false" id="N0745"> </paragraph> + <paragraph role="bascode" localize="false" id="N0746">Public Sub Console_Show()</paragraph> + <paragraph role="bascode" localize="false" id="N0747"> Dim dp as Object ' com.sun.star.awt.DialogProvider2</paragraph> + <paragraph role="bascode" localize="false" id="N0748"> Dim dialog As Object ' com.sun.star.awt.XDialog, com.sun.star.awt.XDialogEventHandler</paragraph> + <paragraph role="bascode" localize="false" id="N0749"> Dim eventHandler As Object ' com.sun.star.awt.XDialogEventHandler</paragraph> + <paragraph role="bascode" localize="false" id="N0750"> dp = CreateUnoService("com.sun.star.awt.DialogProvider2")</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0751"> dp.Initialize(Array(ThisComponent)) ' if doc-embedded dialog</paragraph> + <paragraph role="bascode" localize="false" id="N0752"> eventHandler = CreateUnoListener("Console_", "com.sun.star.awt.XDialogEventHandler")</paragraph> + <paragraph role="bascode" localize="false" id="N0753"> dialog = dp.createDialogWithHandler("vnd.sun.star.script:MyLib.dlgTrace?location=document", eventHandler)</paragraph> + <paragraph role="bascode" localize="false" id="N0754"> dialog.Title = "Konsole"</paragraph> + <paragraph role="bascode" localize="false" id="N0755"> dialog.execute()</paragraph> + <paragraph role="bascode" localize="false" id="N0756">End Sub ' <Handler>.Console_Show()</paragraph> + <paragraph role="bascode" localize="false" id="N0757"> </paragraph> + <paragraph role="bascode" localize="false" id="N0758a">Private Function Console_callHandlerMethod(dialog as Object, _</paragraph> + <paragraph role="bascode" localize="false" id="N0758b"> event As com.sun.star.document.DocumentEvent, _</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0958c"> method As String) As Boolean</paragraph> + <paragraph role="bascode" localize="false" id="N0759"> ''' Intercept dialog events using .UNO protocol '''</paragraph> + <paragraph role="bascode" localize="false" id="N0760"> Console_callHandlerMethod = True</paragraph> + <paragraph role="bascode" localize="false" id="N0761"> Select Case method</paragraph> + <paragraph role="bascode" localize="false" id="N0762"> Case "_dump2File"</paragraph> + <paragraph role="bascode" localize="false" id="N0763"> event.Source.setLabel("dump requested")</paragraph> + <paragraph role="bascode" localize="false" id="N0764"> With GlobalScope.BasicLibraries</paragraph> + <paragraph role="bascode" localize="false" id="N0765"> If Not .IsLibraryLoaded("Access2Base") Then .LoadLibrary("Access2Base")</paragraph> + <paragraph role="bascode" localize="false" id="N0766"> End With</paragraph> + <paragraph role="bascode" localize="false" id="N0767"> Access2Base.Trace._DumpToFile</paragraph> + <paragraph role="bascode" localize="false" id="N0768"> Case "_openHelp" </paragraph> + <paragraph role="bascode" localize="false" id="N0769"> MsgBox "Not yet implemented",0 , "Howdy"</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0770"> 'dialog.endDialog(1) if computer-based dialog</paragraph> + <paragraph role="bascode" localize="false" id="N0771"> Case Else : Console_callHandlerMethod = False</paragraph> + <paragraph role="bascode" localize="false" id="N0772"> End Select</paragraph> + <paragraph role="bascode" localize="false" id="N0773">End Function ' <Handler>.Console_callHandlerMethod</paragraph> + <paragraph role="bascode" localize="false" id="N0774"> </paragraph> + <paragraph role="bascode" localize="false" id="N0775">Private Function Console_getSupportedMethodNames()</paragraph> + <paragraph role="bascode" localize="false" id="N0776"> Console_getSupportedMethodNames = Array("_dump2File", "_openHelp")</paragraph> + <paragraph role="bascode" localize="false" id="N0777">End Function ' <Handler>.Console _getSupportedMethodNames</paragraph> + <paragraph role="bascode" localize="false" id="N0778"> </paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0779">' adapted from « Créer un dialogue avec gestionnaire d'événements » by JM Zambon</paragraph> + <paragraph role="bascode" localize="false" id="N0780">' https://wiki.openoffice.org/wiki/FR/Documentation/Python/Creating_Dialog_with_Handler</paragraph> + </bascode> + <note id="N0781">As expected, <literal>onOkHasFocus</literal> missing method throws an exception.</note> + <section id="relatedtopics" > + <embed href="text/sbasic/python/python_2_basic.xhp#py2ba_h1"/> + <embed href="text/sbasic/guide/show_dialog.xhp#show_dialog"/> + <paragraph role="paragraph" id="N0505"><link href="text/sbasic/shared/03132000.xhp" name ="CreateUnoListener Function">CreateUnoListener Function</link></paragraph> + <embed href="text/sbasic/python/python_listener.xhp#pythonlistener"/> + <embed href="text/sbasic/python/python_dialogs.xhp#pythondialog"/> + <embed href="text/sbasic/python/python_document_events.xhp#pythonmonitor"/> + <embed href="text/sbasic/python/python_examples.xhp#pythonexamples2"/> + <embed href="text/sbasic/python/main0000.xhp#pythonscriptshelp"/> + </section> + </body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/python/python_ide.xhp b/helpcontent2/source/text/sbasic/python/python_ide.xhp new file mode 100644 index 000000000..e6d715630 --- /dev/null +++ b/helpcontent2/source/text/sbasic/python/python_ide.xhp @@ -0,0 +1,36 @@ +<?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="pythonidesetup" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">IDE for Python</title> + <filename>/text/sbasic/python/python_ide.xhp</filename> + </topic> + </meta> + <body> + <section id="pythonideheading"> + <bookmark id="bm_id341543348965463" xml-lang="en-US" branch="hid/zzzz" localize="false"/> + <bookmark xml-lang="en-US" branch="index" id="bm_id761543349138561"> + <bookmark_value>APSO</bookmark_value> + <bookmark_value>Alternative Python Scripts Organizer</bookmark_value> + <bookmark_value>python;IDE - integrated development environment</bookmark_value> + <bookmark_value>python;editor</bookmark_value> + </bookmark> + <h1 id="hd_id151543348965464"><variable id="pythonideh1"><link href="text/sbasic/python/python_ide.xhp" name="Python IDE Setup">Setting up an Integrated Development Environment (IDE) for Python</link></variable></h1> + <paragraph id="par_id541543348965465" role="paragraph" xml-lang="en-US">Writing Python macros requires extra configuration steps to set an IDE of choice.</paragraph> + </section> + <paragraph role="paragraph" id="N0106">Unlike Basic language macros development in %PRODUCTNAME, developing Python scripts for %PRODUCTNAME requires to configure an external Integrated Development Environment (IDE). Multiple IDEs are available that range from beginners to advanced Python coders. While using a Python IDE programmers benefit from numerous features such as syntax highlighting, code folding, class browsing, code completion, coding standard enforcement, test driven development, debugging, version control and many more. You can refer to <link href="https://wiki.documentfoundation.org/Macros/Python_Design_Guide" name="Designing & Developing Python Applications">Designing & Developing Python Applications</link> on the Wiki for more in-depth information about the setup of a bridge between your IDE and a running instance %PRODUCTNAME.</paragraph> + <h2 id="hd_id761544698669786">The APSO Extension</h2> + <paragraph role="paragraph" id="N0104">The <link href="https://extensions.libreoffice.org/extensions/apso-alternative-script-organizer-for-python" name="Alternative Python Script Organizer (APSO)">Alternative Python Script Organizer (APSO)</link> extension eases the edition of Python scripts, in particular when embedded in a document. Using APSO you can configure your preferred source code editor, start the integrated Python shell and debug Python scripts. Extensions exist that help inspect arbitrary UNO objects, refer to <link href="https://wiki.documentfoundation.org/Macros/Python_Design_Guide" name="eDesigning & Developing Python Applications">Designing & Developing Python Applications</link> for additional details on such extensions.</paragraph> + <section id="relatedtopics"> + <embed href="text/sbasic/python/main0000.xhp#pythonscriptshelp"/> + </section> +</body> +</helpdocument>
\ No newline at end of file diff --git a/helpcontent2/source/text/sbasic/python/python_import.xhp b/helpcontent2/source/text/sbasic/python/python_import.xhp new file mode 100644 index 000000000..af3b243d3 --- /dev/null +++ b/helpcontent2/source/text/sbasic/python/python_import.xhp @@ -0,0 +1,118 @@ +<?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="text/sbasic/python/python_import"> + <title id="tit" xml-lang="en-US">Python : Importing Modules</title> + <filename>/text/sbasic/python/python_import.xhp</filename> + </topic> + </meta> + <body> + <bookmark branch="index" id="N0461"> + <bookmark_value>Python;import</bookmark_value> + <bookmark_value>Python;Modules</bookmark_value> + <bookmark_value>Python;pythonpath</bookmark_value> + <bookmark_value>PythonLibraries</bookmark_value> + </bookmark> + <h1 id="N0462"><variable id="pythonimporth1"><link href="text/sbasic/python/python_import.xhp" name="python imports">Importing Python Modules</link></variable></h1> + <paragraph role="paragraph" id="N0463">%PRODUCTNAME Python scripts come in three distinct flavors, they can be personal, shared or embedded in documents. They are stored in varying places described in <link href="text/sbasic/python/python_locations.xhp">Python Scripts Organization and Location</link>. In order to import Python modules, their locations must be known from Python at run time.</paragraph> + <paragraph role="paragraph" id="N0464">This mechanism is illustrated for file system based modules and document based modules. Exception handling is omitted for clarity. The terms library or directory, scripts or modules are used interchangeably. A Python macro refers to a function inside a module.</paragraph> + <warning id="N0465">Note that <literal><User Profile>/Scripts/python/pythonpath</literal> local directory is always explored when running a Python macro from <literal><User Profile>/Scripts/python</literal>.</warning> + <h2 id="N0466">File System module import</h2> + <embed href="text/sbasic/python/python_programming.xhp#PythonFileSystemImport"/> + <h3 id="N0467">User or Shared Modules</h3> + <paragraph role="paragraph" id="N0468">Personal & shared Python scripts can be imported once their directories are included in Python run time path. Refer to <link href="text/sbasic/python/python_session.xhp">Getting session information</link> page for more details regarding omitted Session Class.</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="N0469"># -*- coding: utf-8 -*-</paragraph> + <paragraph role="pycode" localize="false" id="N0470">from __future__ import unicode_literals</paragraph> + <paragraph role="pycode" localize="false" id="N0471">import sys</paragraph> + <paragraph role="pycode" localize="false" id="N0472"> </paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0473">user_lib = Session().UserPythonScripts # User scripts location</paragraph> + <paragraph role="pycode" localize="false" id="N0474">if not user_lib in sys.path:</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0475"> sys.path.insert(0, user_lib) # Add to search path</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0476">import screen_io as ui # 'screen_io.py' module resides in user_lib directory</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0477"># Your code follows here</paragraph> + </pycode> + <paragraph role="paragraph" id="N0478">This Python example exposes a local XSCRIPTCONTEXT variable to an imported module:</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="N0479"># -*- coding: utf-8 -*-</paragraph> + <paragraph role="pycode" localize="false" id="N0480">from __future__ import unicode_literals</paragraph> + <paragraph role="pycode" localize="false" id="N0481">import uno, sys</paragraph> + <paragraph role="pycode" localize="false" id="N0482"> </paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0483">share_lib = Session.SharedPythonScripts() # Shared scripts location</paragraph> + <paragraph role="pycode" localize="false" id="N0484">if not share_lib in sys.path:</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0485"> sys.path.insert(0, share_lib) # Add to search path</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0486">from IDE_utils import ScriptContext # 'IDE_utils.py' sits with shared Python scripts.</paragraph> + <paragraph role="pycode" localize="false" id="N0487">XSCRIPTCONTEXT = ScriptContext(uno.getComponentContext)</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0488"># Your code follows here</paragraph> + </pycode> + <h3 id="N0489">Installation Modules for Applications</h3> + <paragraph role="paragraph" id="N0490">Unlike personal and shared scripts, %PRODUCTNAME installation scripts can be imported any time. Next to <literal>uno</literal> & <literal>unohelper</literal> %PRODUCTNAME Python modules, other scripts present in <literal><installation_path>/program</literal> directory can be imported directly, such as the <literal>msgbox</literal> module.</paragraph> + <paragraph role="paragraph" id="N0491">With Python shell:</paragraph> + <paragraph role="paragraph" localize="false" id="N0492"><literal>>>> import msgbox, uno</literal></paragraph> + <paragraph role="paragraph" localize="false" id="N0494"><literal>>>> myBox = msgbox.MsgBox(uno.getComponentContext())</literal></paragraph> + <paragraph role="paragraph" localize="false" id="N0495"><literal>>>> myBox.addButton("okay")</literal></paragraph> + <paragraph role="paragraph" localize="false" id="N0496"><literal>>>> myBox.renderFromButtonSize()</literal></paragraph> + <paragraph role="paragraph" localize="false" id="N0497"><literal>>>> myBox.numberOflines = 2</literal></paragraph> + <paragraph role="paragraph" localize="false" id="N0499"><literal>>>> print(myBox.show("A small message",0,"Dialog title"))</literal></paragraph> + <h2 id="N0534">Document Module Import</h2> + <paragraph role="paragraph" id="N0535">Importing a Python document embedded module is illustrated below. Error handling is not detailed. Python run time path is updated when document has been opened and before closure. Refer to <link href="text/sbasic/shared/01040000.xhp">Event-Driven Macros</link> to learn how to associate Python macros to document events.</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="N0536"># -*- coding: utf-8 -*-</paragraph> + <paragraph role="pycode" localize="false" id="N0536">from __future__ import unicode_literals</paragraph> + <paragraph role="pycode" localize="false" id="N0537"> </paragraph> + <paragraph role="pycode" localize="false" id="N0538">import sys, uno</paragraph> + <paragraph role="pycode" localize="false" id="N0539"> </paragraph> + <paragraph role="pycode" localize="false" id="N0540">def OnDocPostOpenLoadPython():</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0541"> """ Prepare Python modules import when doc. loaded """</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0542"> PythonLibraries.loadLibrary('lib/subdir') # Add directory to search path </paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0543"> PythonLibraries.loadLibrary('my_gui', 'screen_io') # Add dir. & import screen_io</paragraph> + <paragraph role="pycode" localize="false" id="N0544"> </paragraph> + <paragraph role="pycode" localize="false" id="N0545">def OnDocQueryCloseUnloadPython():</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0546"> """ Cleanup PYTHON_PATH when doc. Gets closed """ </paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0547"> PythonLibraries.unloadLibrary('my_gui') # Python runtime path cleanup</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0548"> # Note: imported modules remain loaded in this example.</paragraph> + <paragraph role="pycode" localize="false" id="N0549"> </paragraph> + <paragraph role="pycode" localize="false" id="N0552">class PythonLibraries():</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0553"> """ Python library loader and module importer</paragraph> + <paragraph role="pycode" localize="false" id="N0554"> </paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0555"> adapted from 'Bibliothèque de fonctions' by Hubert Lambert</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0556"> at https://forum.openoffice.org/fr/forum/viewtopic.php?p=286213 """</paragraph> + <paragraph role="pycode" localize="false" id="N0557"> def isImportedModule(module_name: str) -> bool:</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0558"> """ Check run time module list """</paragraph> + <paragraph role="pycode" localize="false" id="N0559"> return (module_name in sys.modules.keys())</paragraph> + <paragraph role="pycode" localize="false" id="N0560"> def isLoadedLibrary(lib_name: str) -> bool:</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0561"> """ Check PYTHON_PATH content """</paragraph> + <paragraph role="pycode" localize="false" id="N0562"> return (lib_name in sys.path)</paragraph> + <paragraph role="pycode" localize="false" id="N0563"> def loadLibrary(lib_name: str, module_name=None):</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0564"> """ add directory to PYTHON_PATH, import named module """</paragraph> + <paragraph role="pycode" localize="false" id="N0565"> doc = XSCRIPTCONTEXT.getDocument()</paragraph> + <paragraph role="pycode" localize="false" id="N0566"> url = uno.fileUrlToSystemPath(</paragraph> + <paragraph role="pycode" localize="false" id="N0567"> '{}/{}'.format(doc.URL,'Scripts/python/'+lib_name)</paragraph> + <paragraph role="pycode" localize="false" id="N0568"> if not url in sys.path:</paragraph> + <paragraph role="pycode" localize="false" id="N0569"> sys.path.insert(0, url)</paragraph> + <paragraph role="pycode" localize="false" id="N0570"> if module_name and not module_name in sys.modules.keys():</paragraph> + <paragraph role="pycode" localize="false" id="N0571"> return zipimport.zipimporter(url).load_module(module_name)</paragraph> + <paragraph role="pycode" localize="false" id="N0572"> def unloadLibrary(lib_name: str):</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0573"> """ remove directory from PYTHON_PATH """</paragraph> + <paragraph role="pycode" localize="false" id="N0574"> sys.path.remove(lib_name)</paragraph> + <paragraph role="pycode" localize="false" id="N0575"> </paragraph> + <paragraph role="pycode" localize="false" id="N0576">g_exportedScripts = (OnDocPostOpenLoadPython, OnDocQueryCloseUnloadPython)</paragraph> + </pycode> + <section id="relatedtopics" > + <embed href="text/sbasic/python/python_session.xhp#pythonsession"/> + <embed href="text/sbasic/python/python_programming.xhp#pythonprogrammingheading"/> + <embed href="text/sbasic/python/python_locations.xhp#pythonlocations1"/> + <paragraph role="paragraph" id="N0580"> + Refer to <link href="text/sbasic/python/python_listener.xhp">Creating a Python Listener</link> for examples of event-driven macros. + </paragraph> + </section> +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/python/python_listener.xhp b/helpcontent2/source/text/sbasic/python/python_listener.xhp new file mode 100644 index 000000000..c6cdd39f5 --- /dev/null +++ b/helpcontent2/source/text/sbasic/python/python_listener.xhp @@ -0,0 +1,166 @@ +<?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="text/sbasic/python/python_listener.xhp"> + <title id="tit" xml-lang="en-US">Python Listeners : Creating Event Listeners</title> + <filename>/text/sbasic/python/python_listener.xhp</filename> + </topic> + </meta> + <body> + <bookmark branch="index" id="N0385"> + <bookmark_value>Python;Event Listener</bookmark_value> + <bookmark_value>Python;createUnoListener</bookmark_value> + <bookmark_value>Basic;Event Listener</bookmark_value> + <bookmark_value>API;ActionEvent</bookmark_value> + <bookmark_value>API;DialogProvider</bookmark_value> + <bookmark_value>API;EventObject</bookmark_value> + <bookmark_value>API;ExecutableDialogResults</bookmark_value> + <bookmark_value>API;XActionListener</bookmark_value> + </bookmark> + <section id="pythonlistener1"> + <h1 id="N0386"><variable id="pythonlistener"><link href="text/sbasic/python/python_listener.xhp" name="python listeners">Creating Event Listeners</link></variable></h1> + </section> + <paragraph role="paragraph" id="N0387">Events raised by dialogs, documents, forms or graphical controls can be linked to macros, which is referred to as event-driven programming. The most common method to relate events to macros are the <literal>Events</literal> tab in <menuitem>Tools – Customize</menuitem> menu and the <link href="text/sbasic/guide/create_dialog.xhp" name ="Create dialog">Dialog Editor</link> Control properties pane from <menuitem>Tools - Macros – Organise Dialogs...</menuitem> menu.</paragraph> + <paragraph role="paragraph" id="N0388">Graphical artifacts, keyboard inputs, mouse moves and other man/machine interactions can be controlled using UNO listeners that watch for the user’s behaviour. Listeners are dynamic program code alternatives to macro assignments. One may create as many UNO listeners as events to watch for. A single listener can also handle multiple user interface controls.</paragraph> + <h2 id="N0389">Creating an event listener</h2> + <paragraph role="paragraph" id="N0390">Listeners get attached to controls held in dialogs, as well as to document or form events. Listeners are also used when creating runtime dialogs or when adding controls to a dialog on the fly.</paragraph> + <paragraph role="paragraph" id="N0391">This example creates a listener for <literal>Button1</literal> control of <literal>Dialog1</literal> dialog in <literal>Standard</literal> library.</paragraph> + <h3 id="N0392">With Python</h3> + <pycode> + <paragraph role="pycode" localize="false" id="N0393"># -*- coding: utf-8 -*-</paragraph> + <paragraph role="pycode" localize="false" id="N0394">from __future__ import unicode_literals</paragraph> + <paragraph role="pycode" localize="false" id="N0395"> </paragraph> + <paragraph role="pycode" localize="false" id="N0396">import uno, unohelper</paragraph> + <paragraph role="pycode" localize="false" id="N0397">from com.sun.star.awt import XActionListener</paragraph> + <paragraph role="pycode" localize="false" id="N0398">from com.sun.star.awt import ActionEvent</paragraph> + <paragraph role="pycode" localize="false" id="N0399">from com.sun.star.lang import EventObject</paragraph> + <paragraph role="pycode" localize="false" id="N0400">from com.sun.star.ui.dialogs.ExecutableDialogResults \</paragraph> + <paragraph role="pycode" localize="false" id="N0401"> import OK, CANCEL</paragraph> + <paragraph role="pycode" localize="false" id="N0402">import msgbox as util</paragraph> + <paragraph role="pycode" localize="false" id="N0403"> </paragraph> + <paragraph role="pycode" localize="false" id="N0404">_MY_BUTTON = "Button1"</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0405">_MY_LABEL = 'Python listens..'</paragraph> + <paragraph role="pycode" localize="false" id="N0406">_DLG_PROVIDER = "com.sun.star.awt.DialogProvider"</paragraph> + <paragraph role="pycode" localize="false" id="N0407"> </paragraph> + <paragraph role="pycode" localize="false" id="N0408">def Main(*args):</paragraph> + <paragraph role="pycode" localize="false" id="N0409"> ui = createUnoDialog("Standard.Dialog1", embedded=True)</paragraph> + <paragraph role="pycode" localize="false" id="N0410"> ui.Title = "Python X[any]Listener"</paragraph> + <paragraph role="pycode" localize="false" id="N0411"> ctl = ui.getControl(_MY_BUTTON)</paragraph> + <paragraph role="pycode" localize="false" id="N0412"> ctl.Model.Label = _MY_LABEL</paragraph> + <paragraph role="pycode" localize="false" id="N0413"> act = ActionListener()</paragraph> + <paragraph role="pycode" localize="false" id="N0414"> ctl.addActionListener(act)</paragraph> + <paragraph role="pycode" localize="false" id="N0415"> rc = ui.execute()</paragraph> + <paragraph role="pycode" localize="false" id="N0416"> if rc == OK:</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0417"> MsgBox("The user acknowledged the dialog.")</paragraph> + <paragraph role="pycode" localize="false" id="N0418"> elif rc == CANCEL:</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0419"> MsgBox("The user canceled the dialog.")</paragraph> + <paragraph role="pycode" localize="false" id="N0420"> ui.dispose() # ui.endExecute</paragraph> + <paragraph role="pycode" localize="false" id="N0421"> ctl.removeActionListener(act)</paragraph> + <paragraph role="pycode" localize="false" id="N0422"> </paragraph> + <paragraph role="pycode" localize="false" id="N0423">def createUnoDialog(libr_dlg: str, embedded=False):</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0424"> """ Create a Dialog from its location """</paragraph> + <paragraph role="pycode" localize="false" id="N0425"> smgr = XSCRIPTCONTEXT.getComponentContext().ServiceManager</paragraph> + <paragraph role="pycode" localize="false" id="N0426"> if embedded:</paragraph> + <paragraph role="pycode" localize="false" id="N0427"> model = XSCRIPTCONTEXT.getDocument()</paragraph> + <paragraph role="pycode" localize="false" id="N0428"> dp = smgr.createInstanceWithArguments(_DLG_PROVIDER, (model,))</paragraph> + <paragraph role="pycode" localize="false" id="N0429"> location = "?location=document"</paragraph> + <paragraph role="pycode" localize="false" id="N0430"> else:</paragraph> + <paragraph role="pycode" localize="false" id="N0431"> dp = smgr.createInstanceWithContext(_DLG_PROVIDER, ctx)</paragraph> + <paragraph role="pycode" localize="false" id="N0432"> location = "?location=application"</paragraph> + <paragraph role="pycode" localize="false" id="N0433"> dlg = dp.createDialog("vnd.sun.star.script:"+libr_dlg+location)</paragraph> + <paragraph role="pycode" localize="false" id="N0434"> return dlg</paragraph> + <paragraph role="pycode" localize="false" id="N0435"> </paragraph> + <paragraph role="pycode" localize="false" id="N0436">class ActionListener(unohelper.Base, XActionListener):</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0437"> """ Listen to & count button clicks """</paragraph> + <paragraph role="pycode" localize="false" id="N0438"> def __init__(self):</paragraph> + <paragraph role="pycode" localize="false" id="N0439"> self.count = 0</paragraph> + <paragraph role="pycode" localize="false" id="N0440"> </paragraph> + <paragraph role="pycode" localize="false" id="N0441"> def actionPerformed(self, evt: ActionEvent):</paragraph> + <paragraph role="pycode" localize="false" id="N0442"> self.count = self.count + 1</paragraph> + <paragraph role="pycode" localize="false" id="N0443"> #mri(evt)</paragraph> + <paragraph role="pycode" localize="false" id="N0444"> if evt.Source.Model.Name == _MY_BUTTON:</paragraph> + <paragraph role="pycode" localize="false" id="N0445"> evt.Source.Model.Label = _MY_LABEL+ str( self.count )</paragraph> + <paragraph role="pycode" localize="false" id="N0446"> return</paragraph> + <paragraph role="pycode" localize="false" id="N0447"> </paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0448"> def disposing(self, evt: EventObject): # mandatory routine</paragraph> + <paragraph role="pycode" localize="false" id="N0449"> pass</paragraph> + <paragraph role="pycode" localize="false" id="N0450"> </paragraph> + <paragraph role="pycode" localize="false" id="N0451">def MsgBox(txt: str):</paragraph> + <paragraph role="pycode" localize="false" id="N0452"> mb = util.MsgBox(uno.getComponentContext())</paragraph> + <paragraph role="pycode" localize="false" id="N0453"> mb.addButton("Ok")</paragraph> + <paragraph role="pycode" localize="false" id="N0454"> mb.show(txt, 0, "Python")</paragraph> + <paragraph role="pycode" localize="false" id="N0455"> </paragraph> + <paragraph role="pycode" localize="false" id="N0456">g_exportedScripts = (Main,)</paragraph> + </pycode> + <paragraph role="paragraph" id="N0457"> + <emph>msgbox.py</emph> in <emph>{installation}/program/</emph> directory has some examples of button listeners. + </paragraph> + <h3 id="N0458">With %PRODUCTNAME Basic</h3> + <bascode> + <paragraph role="bascode" localize="false" id="N0459a">Option Explicit</paragraph> + <paragraph role="bascode" localize="false" id="N0459b"> </paragraph> + <paragraph role="bascode" localize="false" id="N0459c">Const MY_LIBRARY = "Standard", MY_DIALOG = "Dialog1", MY_BUTTON = "Button1"</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0459d">Const MY_LABEL = "Basic listens.."</paragraph> + <paragraph role="bascode" localize="false" id="N0459e">Dim count As Integer</paragraph> + <paragraph role="bascode" localize="false" id="N0459f"> </paragraph> + <paragraph role="bascode" localize="false" id="N0459">Sub Main</paragraph> + <paragraph role="bascode" localize="false" id="N0460"> Dim libr As Object ' com.sun.star.script.XLibraryContainer</paragraph> + <paragraph role="bascode" localize="false" id="N0461"> Dim dlg As Object</paragraph> + <paragraph role="bascode" localize="false" id="N0462"> Dim ui As Object ' stardiv.Toolkit.UnoDialogControl</paragraph> + <paragraph role="bascode" localize="false" id="N0463"> Dim ctl As Object ' stardiv.Toolkit.UnoButtonControl</paragraph> + <paragraph role="bascode" localize="false" id="N0464"> Dim act As Object ' com.sun.star.awt.XActionListener</paragraph> + <paragraph role="bascode" localize="false" id="N0465"> Dim rc As Object : rc = com.sun.star.ui.dialogs.ExecutableDialogResults</paragraph> + <paragraph role="bascode" localize="false" id="N0466"> </paragraph> + <paragraph role="bascode" localize="false" id="N0467"> BasicLibraries.LoadLibrary(MY_LIBRARY)</paragraph> + <paragraph role="bascode" localize="false" id="N0468"> libr = DialogLibraries.GetByName(MY_LIBRARY)</paragraph> + <paragraph role="bascode" localize="false" id="N0469"> dlg = libr.GetByName(MY_DIALOG)</paragraph> + <paragraph role="bascode" localize="false" id="N0470"> ui = CreateUnoDialog(dlg)</paragraph> + <paragraph role="bascode" localize="false" id="N0471"> ui.Title = "Basic X[any]Listener example"</paragraph> + <paragraph role="bascode" localize="false" id="N0472"> count = 0</paragraph> + <paragraph role="bascode" localize="false" id="N0473"> ctl = ui.GetControl(MY_BUTTON)</paragraph> + <paragraph role="bascode" localize="false" id="N0474"> ctl.Model.Label = MY_LABEL</paragraph> + <paragraph role="bascode" localize="false" id="N0475"> act = CreateUnoListener("awt_", "com.sun.star.awt.XActionListener")</paragraph> + <paragraph role="bascode" localize="false" id="N0476"> ctl.addActionListener(act)</paragraph> + <paragraph role="bascode" localize="false" id="N0477"> Select Case ui.Execute</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0478"> Case rc.OK : MsgBox "The user acknowledged the dialog.",, "Basic"</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0479"> Case rc.CANCEL : MsgBox "The user canceled the dialog.",, "Basic"</paragraph> + <paragraph role="bascode" localize="false" id="N0480"> End Select</paragraph> + <paragraph role="bascode" localize="false" id="N0481"> ui.dispose ' ui.endExecute()</paragraph> + <paragraph role="bascode" localize="false" id="N0482"> ctl.removeActionListener(act)</paragraph> + <paragraph role="bascode" localize="false" id="N0483">End Sub</paragraph> + <paragraph role="bascode" localize="false" id="N0484"> </paragraph> + <paragraph role="bascode" localize="false" id="N0485">Private Sub awt_actionPerformed(evt As com.sun.star.awt.ActionEvent)</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0486"> ''' Listen to & count button clicks '''</paragraph> + <paragraph role="bascode" localize="false" id="N0487"> With evt.Source.Model</paragraph> + <paragraph role="bascode" localize="false" id="N0488"> If .Name = MY_BUTTON Then</paragraph> + <paragraph role="bascode" localize="false" id="N0489"> count = count + 1</paragraph> + <paragraph role="bascode" localize="false" id="N0490"> .Label = MY_LABEL+Cstr(count)</paragraph> + <paragraph role="bascode" localize="false" id="N0491"> End If</paragraph> + <paragraph role="bascode" localize="false" id="N0492"> End With</paragraph> + <paragraph role="bascode" localize="false" id="N0493">End Sub ' awt_actionPerformed</paragraph> + <paragraph role="bascode" localize="false" id="N0494"> </paragraph> + <paragraph role="bascode" localize="false" id="N0495">Private Sub awt_disposing(evt As com.sun.star.lang.EventObject) ' mandatory Sub</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0496"> ' your code goes here</paragraph> + <paragraph role="bascode" localize="false" id="N0497">End Sub ' awt_disposing</paragraph> + </bascode> + <h2 id="N0498">Other Event Listeners</h2> + <paragraph role="paragraph" id="N0499">Listeners are usually coded along with <link href="text/sbasic/python/python_dialogs.xhp" name ="dialog opening">dialog opening</link>. Numerous listener approaches are possible such as event handlers for dialogs or event monitors for documents or forms.</paragraph> + <section id="relatedtopics" > + <embed href="text/sbasic/guide/sample_code.xhp#sample_code"/> + <paragraph role="paragraph" id="N0505"><link href="text/sbasic/shared/03132000.xhp" name ="CreateUnoListener Function">CreateUnoListener Function</link></paragraph> + <paragraph role="paragraph" id="N0506"><link href="text/swriter/01/05060700.xhp" name ="Events mapping to objects">Events mapping to objects</link></paragraph> + <paragraph role="paragraph" id="N0509">See also <link href="text/sbasic/shared/01040000.xhp" name ="Document events">Document events</link>, <link href="text/shared/02/01170202.xhp" name ="Form events">Form events</link>.</paragraph> + <embed href="text/sbasic/python/python_handler.xhp#pythonhandler_h1"/> + <embed href="text/sbasic/python/python_document_events.xhp#pythonmonitor"/> + <embed href="text/sbasic/python/python_examples.xhp#pythonexamples2"/> + </section> + </body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/python/python_locations.xhp b/helpcontent2/source/text/sbasic/python/python_locations.xhp new file mode 100644 index 000000000..4ec027b43 --- /dev/null +++ b/helpcontent2/source/text/sbasic/python/python_locations.xhp @@ -0,0 +1,63 @@ +<?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="pythonlocations" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">Python Scripts Organization</title> + <filename>/text/sbasic/python/python_locations.xhp</filename> + </topic> + </meta> + <body> + <section id="pythonlocation"> + <paragraph id="hd_id391543358231021" role="heading" level="1" xml-lang="en-US"><variable id="pythonlocations1"><link href="text/sbasic/python/python_locations.xhp" name="command_name">Python Scripts Organization and Location</link></variable></paragraph> + <paragraph id="par_id771543358231022" role="paragraph" xml-lang="en-US">The Python script files are stored in the filesystem, in folders controlled by %PRODUCTNAME. The macros can be started at installation, user or file level.</paragraph> + </section> + <h2 id="hd_id911544049584458">Python Script Locations</h2> + <paragraph id="par_id121551089455774" role="paragraph" xml-lang="en-US">Refer to <link href="text/sbasic/python/python_session.xhp" name="Getting Session Information">Getting Session Information</link> in order to get programmatic access to Python script locations.</paragraph> + <h3 id="hd_id591544049572647">%PRODUCTNAME Macros container</h3> + <paragraph role="paragraph" id="par_id261544049064421">Existing macros in this location (container) were copied by the installation program and are available to every computer user, and any open document can access macros stored the container. You need administrative rights to store or edit macros here.</paragraph> + + <paragraph role="paragraph" id="par_id861544210028670">The %PRODUCTNAME Macros container location in the file system depends on the operating system:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id191544210072242" role="listitem">For <emph>Windows</emph>: <literal>{Installation}\share\Scripts\python</literal>.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id61544210078654" role="listitem">For <emph>Linux</emph> and <emph>macOS</emph>: <literal>{Installation}/share/Scripts/python</literal>.</paragraph> + </listitem> + </list> + <h3 id="hd_id861544049692222">My Macros</h3> + <paragraph role="paragraph" id="par_id981544049055996">This container is accessible only by the %PRODUCTNAME user. Any open document can access macros stored the container. Macros in this location are stored in the %PRODUCTNAME user profile.</paragraph> + <paragraph role="paragraph" id="par_id341544210187846">The My Macros container location is in the user space and depends on the operating system:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id381544210213190" role="listitem">For <emph>Windows</emph>,<br/><literal>%APPDATA%\LibreOffice\4\user\Scripts\python</literal>.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id691544210219850" role="listitem">For <emph>Linux</emph> and <emph>macOS</emph>,<br/><literal>$HOME/.config/libreoffice/4/user/Scripts/python</literal>.</paragraph> + </listitem> + </list> + <h3 id="hd_id101544049707712">Document macros</h3> + <paragraph role="paragraph" id="par_id31544049046497">Document macros are embedded in the document and are accessible only when the document is open.</paragraph> + <h2 id="hd_id171544049715310">Libraries, Modules and Macros</h2> + <paragraph role="paragraph" id="par_id181544209916707">Like BASIC macros, Python macros can be organized in libraries, modules and macros.</paragraph> + <h3 id="hd_id21544209865082">Creating a Python Library</h3> + <paragraph role="paragraph" id="par_id191544209928221">Libraries are folders in the container tree. To create a library, add a folder in the target container. The library name is the folder name.</paragraph> + <h3 id="hd_id31544209872869">Creating a Python Module.</h3> + <paragraph role="paragraph" id="par_id161544209936743">A module is a python file in the library or the container. Create a module adding a file in the container.</paragraph> + <h3 id="hd_id151544209895574">Python macros</h3> + <paragraph role="paragraph" id="par_id61544209944591">A macro is a python object in the module.</paragraph> + <section id="relatedtopics"> + <embed href="text/sbasic/python/python_session.xhp#pythonsession"/> + <embed href="text/sbasic/python/main0000.xhp#pythonscriptshelp"/> + </section> +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/python/python_platform.xhp b/helpcontent2/source/text/sbasic/python/python_platform.xhp new file mode 100644 index 000000000..364e067f3 --- /dev/null +++ b/helpcontent2/source/text/sbasic/python/python_platform.xhp @@ -0,0 +1,129 @@ +<?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="text/sbasic/python/Python_Platform"> + <title id="tit" xml-lang="en-US">Python : Platform class</title> + <filename>/text/sbasic/python/python_platform.xhp</filename> + </topic> + </meta> + <body> + <bookmark branch="index" id="N0508"> + <bookmark_value>Platform;isLinux</bookmark_value> + <bookmark_value>Platform;isMacOsX</bookmark_value> + <bookmark_value>Platform;isWindows</bookmark_value> + <bookmark_value>Platform;ComputerName</bookmark_value> + <bookmark_value>Platform;OSName</bookmark_value> + <bookmark_value>API;ConfigurationAccess</bookmark_value> + <bookmark_value>Tools;GetRegistryContent</bookmark_value> + </bookmark> + <h1 id="N0509"><variable id="pythonplatform"><link href="text/sbasic/python/python_platform.xhp" name="platform01">Identifying the operating system</link></variable></h1> + <paragraph role="paragraph" id="N0510">Identifying the operating system can be performed with Python or Basic language.</paragraph> + <note id="N0511">ComputerName property is solely available for Windows. Basic calls to Python macros help overcome %PRODUCTNAME Basic limitations.</note> + <h2 id="N0512">Using a Python class:</h2> + <pycode> + <paragraph role="pycode" localize="false" id="N0513">import os, platform</paragraph> + <paragraph role="pycode" localize="false" id="N0514">class Platform():</paragraph> + <paragraph role="pycode" localize="false" id="N0515"> @property</paragraph> + <paragraph role="pycode" localize="false" id="N0516"> def ComputerName(self): return platform.node()</paragraph> + <paragraph role="pycode" localize="false" id="N0517"> @property</paragraph> + <paragraph role="pycode" localize="false" id="N0518"> def DirSeparator(self): return os.sep</paragraph> + <paragraph role="pycode" localize="false" id="N0519"> @property</paragraph> + <paragraph role="pycode" localize="false" id="N0520"> def isLinux(self): return (self.OSName=='Linux')</paragraph> + <paragraph role="pycode" localize="false" id="N0521"> @property</paragraph> + <paragraph role="pycode" localize="false" id="N0522"> def isMacOSX(self): return (self.OSName=='Darwin')</paragraph> + <paragraph role="pycode" localize="false" id="N0523"> @property</paragraph> + <paragraph role="pycode" localize="false" id="N0524"> def isWindows(self): return (self.OSName=='Windows')</paragraph> + <paragraph role="pycode" localize="false" id="N0525"> @property</paragraph> + <paragraph role="pycode" localize="false" id="N0526"> def OSName(self): return platform.system()</paragraph> + <paragraph role="pycode" localize="false" id="N0527"> @property</paragraph> + <paragraph role="pycode" localize="false" id="N0528"> def PathDelimiter(self): return os.pathsep</paragraph> + </pycode> + <h2 id="N0529">Using a Basic classmodule:</h2> + <tip id="NO529b">%PRODUCTNAME Basic lacks MacOS X native recognition. Platform identification is possible using %PRODUCTNAME Application Programming Interface (API).</tip> + <bascode> + <paragraph role="bascode" localize="false" id="N0530">Option Compatible</paragraph> + <paragraph role="bascode" localize="false" id="N0531">Option ClassModule</paragraph> + <paragraph role="bascode" localize="false" id="N0532">Option Explicit</paragraph> + <paragraph role="bascode" localize="false" id="N0533"></paragraph> + <paragraph role="bascode" localize="false" id="N0534">Public Property Get ComputerName As String</paragraph> + <paragraph role="bascode" localize="false" id="N0535"> If isWindows Then ComputerName = Environ("ComputerName")</paragraph> + <paragraph role="bascode" localize="false" id="N0536">End Property ' Platform.ComputerName</paragraph> + <paragraph role="bascode" localize="false" id="N0537"></paragraph> + <paragraph role="bascode" localize="false" id="N0538">Public Property Get DirSeparator As String</paragraph> + <paragraph role="bascode" localize="false" id="N0539"> DirSeparator = GetPathSeparator()</paragraph> + <paragraph role="bascode" localize="false" id="N0540">End Property ' Platform.DirSeparator</paragraph> + <paragraph role="bascode" localize="false" id="N0541"></paragraph> + <paragraph role="bascode" localize="false" id="N0542">Public Property Get IsLinux As Boolean</paragraph> + <paragraph role="bascode" localize="false" id="N0543"> isLinux = ( GetGUIType()=4 ) ' Applies to macOS as well </paragraph> + <paragraph role="bascode" localize="false" id="N0544">End Property ' Platform.isLinux</paragraph> + <paragraph role="bascode" localize="false" id="N0545"></paragraph> + <paragraph role="bascode" localize="false" id="M0542">Public Property Get IsMacOSX As Boolean</paragraph> + <paragraph role="bascode" localize="false" id="M0543"> isMacOSX = ( OSName="MAC" )</paragraph> + <paragraph role="bascode" localize="false" id="M0544">End Property ' Platform.isMacOSX</paragraph> + <paragraph role="bascode" localize="false" id="M0545"></paragraph> + <paragraph role="bascode" localize="false" id="N0546">Public Property Get IsWindows As Boolean</paragraph> + <paragraph role="bascode" localize="false" id="N0547"> isWindows = ( GetGUIType()=1 )</paragraph> + <paragraph role="bascode" localize="false" id="N0548">End Property ' Platform.isWindows</paragraph> + <paragraph role="bascode" localize="false" id="N0549"></paragraph> + <paragraph role="bascode" localize="false" id="N0550">Public Property Get OSName As String</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0451"> ' Return platform name as "MAC", "UNIX", "WIN"</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0551"> ' Inferred from "Tools.UCB.ShowHelperDialog" function</paragraph> + <paragraph role="bascode" localize="false" id="N0552"> With GlobalScope.Basiclibraries</paragraph> + <paragraph role="bascode" localize="false" id="M0552"> If Not .IsLibraryLoaded("Tools") Then .LoadLibrary("Tools")</paragraph> + <paragraph role="bascode" localize="false" id="O0552"> End With</paragraph> + <paragraph role="bascode" localize="false" id="N0553"> Dim keyNode As Object ' com.sun.star.configuration.ConfigurationAccess</paragraph> + <paragraph role="bascode" localize="false" id="M0553"> keyNode = Tools.Misc.GetRegistryKeyContent("org.openoffice.Office.Common/Help")</paragraph> + <paragraph role="bascode" localize="false" id="N0554"> OSName = keyNode.GetByName("System")</paragraph> + <paragraph role="bascode" localize="false" id="N0555">End Property ' Platform.OSName</paragraph> + <paragraph role="bascode" localize="false" id="N0556"></paragraph> + <paragraph role="bascode" localize="false" id="N0557">Public Property Get PathDelimiter As String</paragraph> + <paragraph role="bascode" localize="false" id="N0559"> Select Case OSName</paragraph> + <paragraph role="bascode" localize="false" id="N0560"> Case "MAC", "UNIX" : PathDelimiter = ":"</paragraph> + <paragraph role="bascode" localize="false" id="N0561"> Case "WIN" : PathDelimiter = ";"</paragraph> + <paragraph role="bascode" localize="false" id="N0562"> End Select</paragraph> + <paragraph role="bascode" localize="false" id="N0563">End Property ' Platform.PathDelimiter</paragraph> + </bascode> + <h2 id="N0564">Examples:</h2> + <paragraph role="paragraph" id="N0565">With Python</paragraph> + <paragraph role="paragraph" localize="false" id="N0566"><literal>>>> from <the_module> import Platform</literal></paragraph> + <paragraph role="paragraph" xml-lang="en-US" id="N0567"><literal>>>> print(Platform().isMacOSX) # object property</literal></paragraph> + <paragraph role="paragraph" localize="false" id="N0568"><literal>True</literal></paragraph> + <paragraph role="paragraph" xml-lang="en-US" id="N0569"><literal>>>> input(Platform().OSName) # object property</literal></paragraph> + <paragraph role="paragraph" localize="false" id="N0570"><literal>Darwin</literal></paragraph> + <paragraph role="paragraph" id="N0571"> + From <menuitem>Tools – Macros - Run Macro...</menuitem> menu.</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="N0572">from <the_module> import Platform</paragraph> + <paragraph role="pycode" localize="false" id="N0573">import screen_io as ui</paragraph> + <paragraph role="pycode" localize="false" id="N0574">p = Platform()</paragraph> + <paragraph role="pycode" localize="false" id="N0575">ui.MsgBox(''.join(['isMacOS: ',str(p.isMacOSX)]),0,p.OSName)</paragraph> + </pycode> + <paragraph role="paragraph" id="N0576">With %PRODUCTNAME Basic</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="N0577">Sub Platform_example()</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0578"> Dim p As New Platform ' instance of Platform class</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0579"> MsgBox p.isLinux ' object property</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0580"> Print p.isWindows, p.OSName ' object properties</paragraph> + <paragraph role="bascode" localize="false" id="N0581">End Sub ' Platform_example</paragraph> + </bascode> + <section id="relatedtopics"> + <embed href="text/sbasic/python/python_screen.xhp#ioscreen"/> + <embed href="text/sbasic/shared/03132100.xhp#getguitype2"/> + <embed href="text/sbasic/shared/GetPathSeparator.xhp#getpathseparator01"/> +<!--WIP + <paragraph role="paragraph" id="N0585"> + <link href="text/sbasic/python/python_from_basic.xhp">Basic to Python function calls</link> + </paragraph>--> + <embed href="text/sbasic/python/python_examples.xhp#pythonexamples2"/> + <embed href="text/sbasic/python/main0000.xhp#pythonscriptshelp"/> + </section> +</body> +</helpdocument>
\ No newline at end of file diff --git a/helpcontent2/source/text/sbasic/python/python_programming.xhp b/helpcontent2/source/text/sbasic/python/python_programming.xhp new file mode 100644 index 000000000..5efa8df15 --- /dev/null +++ b/helpcontent2/source/text/sbasic/python/python_programming.xhp @@ -0,0 +1,319 @@ +<?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="text/sbasic/python/Python_Programming"> + <title id="tit" xml-lang="en-US">Python : Programming with Python</title> + <filename>/text/sbasic/python/python_programming.xhp</filename> + </topic> + </meta> + <body> + <bookmark branch="index" id="N0218"> + <bookmark_value>Python;Programming</bookmark_value> + <bookmark_value>XSCRIPTCONTEXT;Python</bookmark_value> + <bookmark_value>uno.py</bookmark_value> + </bookmark> + <section id="pythonprogramming"> + <h1 id="hd_id691546462755220"><variable id="pythonprogrammingheading"><link href="text/sbasic/python/python_programming.xhp" name="python programming">Programming with Python Scripts</link></variable></h1> + </section> + <paragraph role="paragraph" id="N0220">A Python macro is a function within a .py file, identified as a module. Unlike %PRODUCTNAME Basic and its dozen of <link href="text/sbasic/shared/uno_objects.xhp" name="UNO objects functions or services">UNO objects functions or services</link>, Python macros use the <literal>XSCRIPTCONTEXT</literal> UNO single object, shared with JavaScript and BeanShell. The <literal>g_exportedScripts</literal> global tuple explicitly lists selectable macros from a module. Python modules hold autonomous code logic, and are independent from one another.</paragraph> + <h2 id="N0221">XSCRIPTCONTEXT Global Variable</h2> + <paragraph role="paragraph" id="N0222">Genuine Basic UNO facilities can be inferred from <literal>XSCRIPTCONTEXT</literal> global variable. Refer to %PRODUCTNAME API for a complete <link href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1script_1_1provider_1_1XScriptContext.html" name="description of XSCRIPTCONTEXT">description of XSCRIPTCONTEXT</link>. <literal>XSCRIPTCONTEXT</literal> methods summarize as:</paragraph> + <table id="N0223"> + <tablerow> + <tablecell> + <paragraph role="tablehead" id="N0224">Methods</paragraph> + </tablecell> + <tablecell> + <paragraph role="tablehead" id="N0225">Description</paragraph> + </tablecell> + <tablecell> + <paragraph role="tablehead" id="N0226">Mapped in Basic as</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph role="tablecontent" localize="false" id="N0227">getDocument()</paragraph> + </tablecell> + <tablecell> + <paragraph role="tablecontent" id="N0228">The document reference on which the script can operate.</paragraph> + </tablecell> + <tablecell> + <paragraph role="tablecontent" localize="false" id="N0229">ThisComponent</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph role="tablecontent" localize="false" id="N0230">getDesktop()</paragraph> + </tablecell> + <tablecell> + <paragraph role="tablecontent" id="N0231">The desktop reference on which the script can operate.</paragraph> + </tablecell> + <tablecell> + <paragraph role="tablecontent" localize="false" id="N0232">StarDesktop</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph role="tablecontent" localize="false" id="N0233">getComponentContext()</paragraph> + </tablecell> + <tablecell> + <paragraph role="tablecontent" id="N0234">The component context which the script can use to create other uno components.</paragraph> + </tablecell> + <tablecell> + <paragraph role="tablecontent" localize="false" id="N0235">GetDefaultContext</paragraph> + </tablecell> + </tablerow> + </table> + <paragraph role="paragraph" id="N0237"><emph>HelloWorld</emph> and <emph>Capitalise</emph> installation shared scripts illustrate UNO-related macros making use of <literal>XSCRIPTCONTEXT</literal> global variable.</paragraph> + <tip id="N0238">Python standard output file is not available when running Python macros from <menuitem>Tools - Macros - Run Macro</menuitem> menu. Refer to <emph>Input/Output to Screen</emph> for more information.</tip> + <h2 id="N0239">Module import</h2> + <warning id="N0240"><literal>XSCRIPTCONTEXT</literal> is not provided to imported modules.</warning> + <section id="PythonFileSystemImport" > + <paragraph role="paragraph" id="N0241">%PRODUCTNAME Basic libraries contain classes, routines and variables, Python modules contain classes, functions and variables. Common pieces of reusable Python or UNO features must be stored in <link href="text/sbasic/python/python_locations.xhp" name="My macros">My macros</link> within <literal>(User Profile)/Scripts/python/pythonpath</literal>. Python libraries help organize modules in order to prevent module name collisions. Import <literal>uno.py</literal> inside shared modules.</paragraph> + </section> + <paragraph role="paragraph" id="N0242">Genuine BASIC UNO facilities can be inferred using <literal>uno.py</literal> module. Use <link href="text/sbasic/python/python_shell.xhp" name="Python interactive shell">Python interactive shell</link> to get a complete module description using <literal>dir()</literal> and <literal>help()</literal> Python commands.</paragraph> + <table id="N0243"> + <tablerow> + <tablecell> + <paragraph role="tablehead" id="N0244">Functions</paragraph> + </tablecell> + <tablecell> + <paragraph role="tablehead" id="N0245">Description</paragraph> + </tablecell> + <tablecell> + <paragraph role="tablehead" id="N0246">Mapped in Basic as</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph role="tablecontent" localize="false" id="N0247">absolutize()</paragraph> + </tablecell> + <tablecell> + <paragraph role="tablecontent" id="N0248">Returns an absolute file url from the given urls.</paragraph> + </tablecell> + <tablecell> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph role="tablecontent" localize="false" id="N0250">createUnoStruct()</paragraph> + </tablecell> + <tablecell> + <paragraph role="tablecontent" id="N0251">Creates a UNO struct or exception given by typeName.</paragraph> + </tablecell> + <tablecell> + <paragraph role="tablecontent" localize="false" id="N0252">CreateUNOStruct()</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph role="tablecontent" localize="false" id="N0253">fileUrlToSystemPath()</paragraph> + </tablecell> + <tablecell> + <paragraph role="tablecontent" id="N0254">Returns a system path.</paragraph> + </tablecell> + <tablecell> + <paragraph role="tablecontent" localize="false" id="N0255">ConvertFromURL()</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph role="tablecontent" localize="false" id="N0256">getClass()</paragraph> + </tablecell> + <tablecell> + <paragraph role="tablecontent" id="N0257">Returns the class of a concrete UNO exception, struct, or interface.</paragraph> + </tablecell> + <tablecell> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph role="tablecontent" localize="false" id="N0259">getComponentContext()</paragraph> + </tablecell> + <tablecell> + <paragraph role="tablecontent" id="N0260">Returns the UNO component context used to initialize the Python runtime.</paragraph> + </tablecell> + <tablecell> + <paragraph role="tablecontent" localize="false" id="N0261">GetDefaultContext()</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph role="tablecontent" localize="false" id="N0262">Enum()</paragraph> + <paragraph role="tablecontent" localize="false" id="N0263">getConstantByName()</paragraph> + </tablecell> + <tablecell> + <paragraph role="tablecontent" id="N0264">Looks up the value of an IDL constant by giving its explicit name.</paragraph> + </tablecell> + <tablecell> + <paragraph role="tablecontent" id="N0265">See API constant groups</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph role="tablecontent" localize="false" id="N0266">isInterface()</paragraph> + </tablecell> + <tablecell> + <paragraph role="tablecontent" id="N0267">Returns True, when obj is a class of a UNO interface.</paragraph> + </tablecell> + <tablecell> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph role="tablecontent" localize="false" id="N0269">systemPathToFileUrl()</paragraph> + </tablecell> + <tablecell> + <paragraph role="tablecontent" id="N0270">Returns a file URL for the given system path.</paragraph> + </tablecell> + <tablecell> + <paragraph role="tablecontent" localize="false" id="N0271">ConvertToURL()</paragraph> + </tablecell> + </tablerow> + </table> + <paragraph role="paragraph" id="N0272"><emph>LibreLogo</emph> and <emph>TableSample</emph> installation shared scripts use <literal>uno.py</literal> module.</paragraph> + <h2 id="N0273">More Python-Basic samples</h2> + <table id="N0274"> + <tablerow> + <tablecell> + <paragraph role="tablehead" id="N0275">Python UNO</paragraph> + </tablecell> + <tablecell> + <paragraph role="tablehead" id="N0276">Basic UNO features</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph role="tablecontent" localize="false" id="N0277">ctx = uno.getComponentContext()</paragraph> + <paragraph role="tablecontent" localize="false" id="N0278">smgr = ctx.getServiceManager()</paragraph> + <paragraph role="tablecontent" localize="false" id="N0279">obj = smgr.createInstanceWithContext( .. , ctx)</paragraph> + </tablecell> + <tablecell> + <paragraph role="tablecontent" localize="false" id="N0280">CreateUnoService()</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph role="tablecontent" id="N0284">See <link href="text/sbasic/python/python_dialogs.xhp" name="Opening a Dialog">Opening a Dialog</link></paragraph> + </tablecell> + <tablecell> + <paragraph role="tablecontent" localize="false" id="N0285">CreateUnoDialog()</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph role="tablecontent" id="N0286">See <link href="text/sbasic/python/python_listener.xhp" name="Creating a Listener">Creating a Listener</link></paragraph> + </tablecell> + <tablecell> + <paragraph role="tablecontent" localize="false" id="N0287">CreateUnoListener()</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph role="tablecontent" id="N0288">See UNO data types</paragraph> + </tablecell> + <tablecell> + <paragraph role="tablecontent" localize="false" id="N0289">CreateUnoValue()</paragraph> + <paragraph role="tablecontent" localize="false" id="N0290">CreateObject()</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + </tablecell> + <tablecell> + <paragraph role="tablecontent" localize="false" id="N0292">EqualUnoObjects()</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph role="tablecontent" localize="false" id="N0281">ctx = uno.getComponentContext()</paragraph> + <paragraph role="tablecontent" localize="false" id="N0282">smgr = ctx.getServiceManager()</paragraph> + </tablecell> + <tablecell> + <paragraph role="tablecontent" localize="false" id="N0283">GetProcessServiceManager()</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph role="tablecontent" localize="false" id="N0292">def hasUnoInterfaces(obj, *interfaces):</paragraph> + <paragraph role="tablecontent" localize="false" id="N0293">return set(interfaces).issubset(t.typeName for t in obj.Types)</paragraph> + <!-- Credits: + [Python]Equivalent 'supportsService' by Hubert Lambert + @ https://forum.openoffice.org/fr/forum/viewtopic.php?f=8&t=56597 + --> + </tablecell> + <tablecell> + <paragraph role="tablecontent" localize="false" id="N0294">HasUnoInterfaces()</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + </tablecell> + <tablecell> + <paragraph role="tablecontent" localize="false" id="N0296">IsUnoStruct()</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph role="tablecontent" localize="false" id="N0297">ctx = uno.getComponentContext()</paragraph> + <paragraph role="tablecontent" localize="false" id="N0298">smgr = ctx.getServiceManager()</paragraph> + <paragraph role="tablecontent" localize="false" id="N0299">DESK = 'com.sun.star.frame.Desktop'</paragraph> + <paragraph role="tablecontent" localize="false" id="N0300">desktop = smgr.createInstanceWithContext(DESK , ctx)</paragraph> + </tablecell> + <tablecell> + <paragraph role="tablecontent" localize="false" id="N0301">StarDesktop</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph role="tablecontent" localize="false" id="N0298">desktop = smgr.createInstanceWithContext(DESK , ctx)</paragraph> + <paragraph role="tablecontent" localize="false" id="N0299">doc = desktop.CurrentComponent</paragraph> + </tablecell> + <tablecell> + <paragraph role="tablecontent" localize="false" id="N0301">ThisComponent</paragraph> + </tablecell> + </tablerow> + </table> + <h2 id="N0297">Importing an embedded Module</h2> + <section id="PythonEmbeddedImport" > + <paragraph role="paragraph" id="N0298">Similarly to %PRODUCTNAME Basic that supports browsing and dynamic loading of libraries, Python libraries can be explored and imported on demand. For more information on library containers, visit <link href="https://api.libreoffice.org/" name="API Documentation site">%PRODUCTNAME Application Programming Interface</link> (API) or download <link href="https://www.libreoffice.org/download/download/" name="SDK download page">%PRODUCTNAME Software Development Kit</link> (SDK).</paragraph> + <paragraph role="paragraph" id="N0299">Importing a Python document embedded module is illustrated below, exception handling is not detailed:</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="N0300">import uno, sys</paragraph> + <paragraph role="pycode" localize="false" id="N0301"></paragraph> + <paragraph role="pycode" localize="false" id="N0302">def load_library(library_name: str, module_name=None):</paragraph> + <paragraph role="pycode" id="N0303"> """ load library and import module</paragraph> + <paragraph role="pycode" localize="false" id="N0304"> </paragraph> + <paragraph role="pycode" id="N0305"> Adapted from 'Bibliothèque de fonctions' by Hubert Lambert</paragraph> + <paragraph role="pycode" id="N0306"> at https://forum.openoffice.org/fr/forum/viewtopic.php?p=286213"""</paragraph> + <paragraph role="pycode" id="N0307"> doc = XSCRIPTCONTEXT.getDocument() # current document</paragraph> + <paragraph role="pycode" localize="false" id="N0308"> url = uno.fileUrlToSystemPath( \</paragraph> + <paragraph role="pycode" localize="false" id="N0309"> '{}/{}'.format(doc.URL, 'Scripts/python'+library_name)) # ConvertToURL()</paragraph> + <paragraph role="pycode" id="N0310"> if not url in sys.path: # add path if necessary</paragraph> + <paragraph role="pycode" id="N0311"> sys.path.insert(0, url) # doclib takes precedence</paragraph> + <paragraph role="pycode" id="N0312"> if module_name: # import if requested</paragraph> + <paragraph role="pycode" localize="false" id="N0313"> return zipimport.zipimporter(url).load_module(module_name)</paragraph> + <paragraph role="pycode" localize="false" id="N0314"></paragraph> + <paragraph role="pycode" localize="false" id="N0315">def import_embedded_python():</paragraph> + <paragraph role="pycode" id="N0316"> ui = load_library("my_gui",'screen_io') # add <lib> path + import <module> </paragraph> + <paragraph role="pycode" localize="false" id="N0317"> ui.MsgBox(sys.modules.keys())</paragraph> + <paragraph role="pycode" localize="false" id="N0314"></paragraph> + <paragraph role="pycode" localize="false" id="N0319">g_exportedScripts = (import_embedded_python,) # Public macros</paragraph> + </pycode> + </section> + <section id="relatedtopics"> + <paragraph role="paragraph" id="N0321"><link href="text/sbasic/shared/uno_objects.xhp" name="UNO objects page">Basic UNO Objects, Functions and Services</link></paragraph> + <embed href="text/sbasic/python/python_import.xhp#pythonimporth1"/> + <embed href="text/sbasic/python/python_screen.xhp#ioscreen"/> + <embed href="text/sbasic/python/main0000.xhp#pythonscriptshelp"/> + </section> +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/python/python_screen.xhp b/helpcontent2/source/text/sbasic/python/python_screen.xhp new file mode 100644 index 000000000..b88fa923a --- /dev/null +++ b/helpcontent2/source/text/sbasic/python/python_screen.xhp @@ -0,0 +1,108 @@ +<?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="text/sbasic/python/python_screen"> + <title id="tit">Python : Screen Input/Output</title> + <filename>/text/sbasic/python/python_screen.xhp</filename> + </topic> + </meta> + <body> + <bookmark branch="index" xml-lang="en-US" id="N0433"> + <bookmark_value>Python;InputBox</bookmark_value> + <bookmark_value>Python;MsgBox</bookmark_value> + <bookmark_value>Python;Print</bookmark_value> + <bookmark_value>API;script.provider.MasterScriptProvider: Screen Input/Output</bookmark_value> + <bookmark_value>API;script.provider.XScript: Screen Input/Output</bookmark_value> + </bookmark> + <h1 id="N0434"><variable id="ioscreen"><link href="text/sbasic/python/python_screen.xhp" name="IO to screen">Input/Output to Screen</link></variable></h1> + <paragraph role="paragraph" id="N0435">Python standard output file is not available when running Python macros from <menuitem>Tools – Macros - Run Macro</menuitem>... menu. Presenting the output of a module requires the Python interactive console. Features such as <literal>input()</literal>, <literal>print()</literal>, <literal>repr()</literal> and <literal>str()</literal> are available from the Python shell.</paragraph> + <paragraph role="tip" id="N0436">The <link href="https://extensions.libreoffice.org/extensions/apso-alternative-script-organizer-for-python" name="apso">Alternative Python Script Organizer</link> (APSO) extension offers a msgbox() function out of its <literal>apso_utils</literal> module.</paragraph> + <paragraph role="paragraph" id="N0437">%PRODUCTNAME Basic proposes <literal>InputBox()</literal>, <literal>Msgbox()</literal> and <literal>Print()</literal> screen I/O functions. Python alternatives exist relying either on %PRODUCTNAME API Abstract Windowing Toolkit, either on Python to Basic function calls. The latter proposes a syntax that is intentionally close to that of Basic, and uses a Python module next to a Basic module. The API Scripting Framework is used to perform Basic, BeanShell, JavaScript and Python inter-languages function calls.</paragraph> + <h2 id="N0438">Python syntax:</h2> + <paragraph role="code" id="N0439" localize="false">MsgBox(txt, buttons=0, title=None)<br/></paragraph> + <paragraph role="code" id="N0440" localize="false">InputBox(txt, title=None, default=None)<br/></paragraph> + <paragraph role="code" id="N0441" localize="false">Print(txt)</paragraph> + <h2 id="N0442">Examples:</h2> + <paragraph role="paragraph" localize="false" id="N0443"><literal>>>> import screen_io as ui</literal></paragraph> + <paragraph role="paragraph" localize="false" id="N0445"><literal>>>> reply = ui.InputBox('Please enter a phrase', title='Dear user', defaultValue="here..")</literal></paragraph> + <paragraph role="paragraph" localize="false" id="N0446"><literal>>>> rc = ui.MsgBox(reply, title="Confirmation of phrase")</literal></paragraph> + <paragraph role="paragraph" localize="false" id="N0447"><literal>>>> age = ui.InputBox('How old are you?', title="Hi")</literal></paragraph> + <paragraph role="paragraph" localize="false" id="N0448"><literal>>>> ui.Print(age)</literal></paragraph> + <h2 id="N0449">Installation:</h2> + <list type="unordered"> + <listitem> + <paragraph role="listitem" id="N0450">Copy <literal>screen_io</literal> Python module in <link href="text/sbasic/python/python_locations.xhp" name="User macros">My macros</link> within <UserProfile>/Scripts/python/pythonpath,</paragraph> + </listitem> + <listitem> + <paragraph role="listitem" id="N0451">Copy <literal>uiScripts</literal> Basic module in <link href="text/sbasic/python/python_locations.xhp" name="User macros">My macros</link> Standard Basic library,</paragraph> + </listitem> + <listitem> + <paragraph role="listitem" id="N0452">Restart %PRODUCTNAME.</paragraph> + </listitem> + </list> + <h3 id="N0453"><literal>screen_io</literal> Python module</h3> + <pycode> + <paragraph role="pycode" localize="false" id="N0454"># -*- coding: utf-8 -*-</paragraph> + <paragraph role="pycode" localize="false" id="N0455">from __future__ import unicode_literals</paragraph> + <paragraph role="pycode" localize="false" id="N0456"></paragraph> + <paragraph role="pycode" localize="false" id="N0466">def MsgBox(prompt: str, buttons=0, title='LibreOffice') -> int:</paragraph> + <paragraph role="pycode" id="N0467"> """ Displays a dialog box containing a message and returns a value."""</paragraph> + <paragraph role="pycode" localize="false" id="N0468"> xScript = _getScript("_MsgBox")</paragraph> + <paragraph role="pycode" localize="false" id="N0469"> res = xScript.invoke((prompt,buttons,title), (), ())</paragraph> + <paragraph role="pycode" localize="false" id="N0470"> return res[0]</paragraph> + <paragraph role="pycode" localize="false" id="N0471"></paragraph> + <paragraph role="pycode" localize="false" id="N0472">def InputBox(prompt: str, title='LibreOffice', defaultValue='') -> str:</paragraph> + <paragraph role="pycode" id="N0473"> """ Displays a prompt in a dialog box at which the user can enter text."""</paragraph> + <paragraph role="pycode" localize="false" id="N0474"> xScript = _getScript("_InputBox")</paragraph> + <paragraph role="pycode" localize="false" id="N0475"> res = xScript.invoke((prompt,title,defaultValue), (), ())</paragraph> + <paragraph role="pycode" localize="false" id="N0476"> return res[0]</paragraph> + <paragraph role="pycode" localize="false" id="N0477"></paragraph> + <paragraph role="pycode" localize="false" id="N0478">def Print(message: str):</paragraph> + <paragraph role="pycode" id="N0479"> """Outputs the specified strings or numeric expressions in a dialog box."""</paragraph> + <paragraph role="pycode" localize="false" id="N0480"> xScript = _getScript("_Print")</paragraph> + <paragraph role="pycode" localize="false" id="N0481"> xScript.invoke((message,), (), ())</paragraph> + <paragraph role="pycode" localize="false" id="N0482"></paragraph> + <paragraph role="pycode" localize="false" id="N0483">import uno</paragraph> + <paragraph role="pycode" localize="false" id="N0484">from com.sun.star.script.provider import XScript</paragraph> + <paragraph role="pycode" localize="false" id="N0485">def _getScript(script: str, library='Standard', module='uiScripts') -> XScript:</paragraph> + <paragraph role="pycode" localize="false" id="N0486"> sm = uno.getComponentContext().ServiceManager</paragraph> + <paragraph role="pycode" localize="false" id="N0487"> mspf = sm.createInstanceWithContext("com.sun.star.script.provider.MasterScriptProviderFactory", uno.getComponentContext())</paragraph> + <paragraph role="pycode" localize="false" id="N0488"> scriptPro = mspf.createScriptProvider("")</paragraph> + <paragraph role="pycode" localize="false" id="N0489"> scriptName = "vnd.sun.star.script:"+library+"."+module+"."+script+"?language=Basic&location=application"</paragraph> + <paragraph role="pycode" localize="false" id="N0490"> xScript = scriptPro.getScript(scriptName)</paragraph> + <paragraph role="pycode" localize="false" id="N0491"> return xScript</paragraph> + </pycode> + <h3 id="N0492"><literal>uiScripts</literal> Basic module</h3> + <bascode> + <paragraph role="bascode" localize="false" id="N0493">Option Explicit</paragraph> + <paragraph role="bascode" localize="false" id="N0494">Private Function _MsgBox( prompt As String, Optional buttons As Integer, _</paragraph> + <paragraph role="bascode" localize="false" id="N0495"> Optional title As String ) As Integer</paragraph> + <paragraph role="bascode" localize="false" id="N0496"> _MsgBox = MsgBox( prompt, buttons, title )</paragraph> + <paragraph role="bascode" localize="false" id="N0497">End Function</paragraph> + <paragraph role="bascode" localize="false" id="N0498">Private Function _InputBox( prompt As String, Optional title As String, _</paragraph> + <paragraph role="bascode" localize="false" id="N0499"> Optional default As String) As String</paragraph> + <paragraph role="bascode" localize="false" id="N0500"> _InputBox = InputBox( prompt, title, default )</paragraph> + <paragraph role="bascode" localize="false" id="N0501">End Function</paragraph> + <paragraph role="bascode" localize="false" id="N0502">Private Sub _Print( msg As String )</paragraph> + <paragraph role="bascode" localize="false" id="N0503"> Print msg</paragraph> + <paragraph role="bascode" localize="false" id="N0504">End Sub</paragraph> + </bascode> + <section id="relatedtopics"> + <!-- + <paragraph role="paragraph" id="N0505"><link href="text/sbasic/python/python_2_basic.xhp" name="Calling Basic macros from Python">Calling Basic macros from Python</link></paragraph> + --> + <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> diff --git a/helpcontent2/source/text/sbasic/python/python_session.xhp b/helpcontent2/source/text/sbasic/python/python_session.xhp new file mode 100644 index 000000000..f8c378dee --- /dev/null +++ b/helpcontent2/source/text/sbasic/python/python_session.xhp @@ -0,0 +1,158 @@ +<?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="text/sbasic/python/python_session"> + <title id="tit" xml-lang="en-US">Python_Session : Session class</title> + <filename>/text/sbasic/python/python_session.xhp</filename> + </topic> + </meta> + <body> + <bookmark branch="index" id="N0339"> + <bookmark_value>Session;UserName</bookmark_value> + <bookmark_value>Session;SharedScripts</bookmark_value> + <bookmark_value>Session;SharedPythonScripts</bookmark_value> + <bookmark_value>Session;UserProfile</bookmark_value> + <bookmark_value>Session;UserScripts</bookmark_value> + <bookmark_value>Session;UserPythonScripts</bookmark_value> + <bookmark_value>API;PathSubstitution</bookmark_value> + </bookmark> + <h1 id="N0340"><variable id="pythonsession"><link href="text/sbasic/python/python_session.xhp" name="session01">Getting Session Information</link></variable></h1> + <paragraph role="paragraph" id="N0341">Computing %PRODUCTNAME user profile and shared modules system file paths can be performed with Python or with Basic languages. BeanShell, Java, JavaScript and Python scripts locations can be derived from this information.</paragraph> + <h2 id="N0343">Examples:</h2> + <paragraph role="paragraph" id="N0344">With Python shell.</paragraph> + <paragraph role="paragraph" localize="false" id="N0345"><literal>>>> from <the_module> import Session</literal></paragraph> + <paragraph role="paragraph" xml-lang="en-US" id="N0346"><literal>>>> print(Session.SharedPythonScripts()) # static method</literal></paragraph> + <paragraph role="paragraph" xml-lang="en-US" id="N0347"><literal>>>> print(Session().UserName) # object property</literal></paragraph> + <paragraph role="paragraph" xml-lang="en-US" id="N0348"><literal>>>> input(Session().UserProfile) # object property</literal></paragraph> + <h3 id="N0349">From <menuitem>Tools – Macros - Run Macro</menuitem>... menu.</h3> + <pycode> + <paragraph role="pycode" localize="false" id="N0350">from <the_module> import Session</paragraph> + <paragraph role="pycode" localize="false" id="N0351"> </paragraph> + <paragraph role="pycode" localize="false" id="N0352">def demo_session():</paragraph> + <paragraph role="pycode" localize="false" id="N0353"> import screen_io as ui</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0354"> ui.MsgBox(Session.Share(),title='Installation Share') # static method</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0355"> ui.Print(Session.SharedPythonScripts()) # static method</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0356"> s = Session() # instance creation</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0357"> ui.MsgBox(s.UserName,title='Hello') # object property</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0358"> ui.Print(s.UserPythonScripts) # object property</paragraph> + <paragraph role="pycode" localize="false" id="N0359"> </paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0360">g_exportedScripts = (demo_session,) # public macros</paragraph> + </pycode> + <h3 id="N0361">With %PRODUCTNAME Basic.</h3> + <bascode> + <paragraph role="bascode" localize="false" id="N0362">Sub Session_example()</paragraph> + <paragraph role="bascode" localize="false" id="N0363"> Dim s As New Session ' instance of Session class</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0364"> Print "Shared scripts location:", s.SharedScripts</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0365"> MsgBox s.UserName,,"Hello"</paragraph> + <paragraph role="bascode" localize="false" id="N0366"> Print s.UserScripts, Chr(13), s.UserPythonScripts</paragraph> + <paragraph role="bascode" localize="false" id="N0367">End Sub ' Session_example</paragraph> + </bascode> + <h3 id="N0368">Using COM/OLE and Visual Basic Scripting language.</h3> + <bascode> + <paragraph role="bascode" xml-lang="en-US" id="N0369">' The service manager is always the entry point</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0370">' If there is no office running then an office is started up</paragraph> + <paragraph role="bascode" localize="false" id="N0371">Set sm = WScript.CreateObject("com.sun.star.ServiceManager")</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0372">' PathSubstitution service exhibits information to infer</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0373">' <UserProfile|Share>/Scripts/python locations from</paragraph> + <paragraph role="bascode" localize="false" id="N0374">Set obj = sm.createInstance("com.sun.star.util.PathSubstitution")</paragraph> + <paragraph role="bascode" localize="false" id="N0375"> </paragraph> + <paragraph role="bascode" localize="false" id="N0376">MsgBox CreateObject("WScript.Network").UserName,, "Hello"</paragraph> + <paragraph role="bascode" localize="false" id="N0377">user = obj.getSubstituteVariableValue("$(user)")</paragraph> + <paragraph role="bascode" localize="false" id="N0378">MsgBox user & "/Scripts",, "User scripts location"</paragraph> + <paragraph role="bascode" localize="false" id="N0379">libO = Replace(obj.getSubstituteVariableValue("$(inst)"), "program/..", "Share")</paragraph> + <paragraph role="bascode" localize="false" id="N0380">MsgBox libO & "/Scripts",, "Shared scripts location"</paragraph> + </bascode> + <h2 id="N0381">Python Session class:</h2> + <pycode> + <paragraph role="pycode" localize="false" id="N0382">import getpass, os, os.path, uno</paragraph> + <paragraph role="pycode" localize="false" id="N0383"> </paragraph> + <paragraph role="pycode" localize="false" id="N0384">class Session():</paragraph> + <paragraph role="pycode" localize="false" id="N0385"> @staticmethod</paragraph> + <paragraph role="pycode" localize="false" id="N0386"> def substitute(var_name):</paragraph> + <paragraph role="pycode" localize="false" id="N0387"> ctx = uno.getComponentContext()</paragraph> + <paragraph role="pycode" localize="false" id="N0388"> ps = ctx.getServiceManager().createInstanceWithContext(</paragraph> + <paragraph role="pycode" localize="false" id="N0389"> 'com.sun.star.util.PathSubstitution', ctx)</paragraph> + <paragraph role="pycode" localize="false" id="N0390"> return ps.getSubstituteVariableValue(var_name)</paragraph> + <paragraph role="pycode" localize="false" id="N0391"> @staticmethod</paragraph> + <paragraph role="pycode" localize="false" id="N0392"> def Share():</paragraph> + <paragraph role="pycode" localize="false" id="N0393"> inst = uno.fileUrlToSystemPath(Session.substitute("$(prog)"))</paragraph> + <paragraph role="pycode" localize="false" id="N0394"> return os.path.normpath(inst.replace('program', "Share"))</paragraph> + <paragraph role="pycode" localize="false" id="N0395"> @staticmethod</paragraph> + <paragraph role="pycode" localize="false" id="N0396"> def SharedScripts():</paragraph> + <paragraph role="pycode" localize="false" id="N0397"> return ''.join([Session.Share(), os.sep, "Scripts"])</paragraph> + <paragraph role="pycode" localize="false" id="N0398"> @staticmethod</paragraph> + <paragraph role="pycode" localize="false" id="N0399"> def SharedPythonScripts():</paragraph> + <paragraph role="pycode" localize="false" id="N0400"> return ''.join([Session.SharedScripts(), os.sep, 'python'])</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="N0401"> @property # alternative to '$(username)' variable</paragraph> + <paragraph role="pycode" localize="false" id="N0402"> def UserName(self): return getpass.getuser()</paragraph> + <paragraph role="pycode" localize="false" id="N0403"> @property</paragraph> + <paragraph role="pycode" localize="false" id="N0404"> def UserProfile(self):</paragraph> + <paragraph role="pycode" localize="false" id="N0405"> return uno.fileUrlToSystemPath(Session.substitute("$(user)"))</paragraph> + <paragraph role="pycode" localize="false" id="N0406"> @property</paragraph> + <paragraph role="pycode" localize="false" id="N0407"> def UserScripts(self):</paragraph> + <paragraph role="pycode" localize="false" id="N0408"> return ''.join([self.UserProfile, os.sep, 'Scripts'])</paragraph> + <paragraph role="pycode" localize="false" id="N0409"> @property</paragraph> + <paragraph role="pycode" localize="false" id="N0410"> def UserPythonScripts(self):</paragraph> + <paragraph role="pycode" localize="false" id="N0411"> return ''.join([self.UserScripts, os.sep, "python"])</paragraph> + </pycode> + <note id="N0342">Unlike Basic, pathname normalization is performed with Python inside Session class.</note> + <h2 id="N0412">%PRODUCTNAME Basic Session class:</h2> + <bascode> + <paragraph role="bascode" localize="false" id="N0413">Option Explicit</paragraph> + <paragraph role="bascode" localize="false" id="N0414">Option Compatible</paragraph> + <paragraph role="bascode" localize="false" id="N0415">Option ClassModule</paragraph> + <paragraph role="bascode" localize="false" id="N0416"> </paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0417">Private _ps As Object ' Private member</paragraph> + <paragraph role="bascode" localize="false" id="N0418"> </paragraph> + <paragraph role="bascode" localize="false" id="N0419">Private Sub Class_Initialize()</paragraph> + <paragraph role="bascode" localize="false" id="N0420"> GlobalScope.BasicLibraries.LoadLibrary("Tools")</paragraph> + <paragraph role="bascode" localize="false" id="N0421"> Set _ps = CreateUnoService("com.sun.star.util.PathSubstitution")</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0422">End Sub ' Constructor</paragraph> + <paragraph role="bascode" localize="false" id="N0423"> </paragraph> + <paragraph role="bascode" localize="false" id="N0424">Private Sub Class_Terminate()</paragraph> + <paragraph role="bascode" localize="false" id="N0425"> _ps = Nothing</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0426">End Sub ' Destructor</paragraph> + <paragraph role="bascode" localize="false" id="N0427"> </paragraph> + <paragraph role="bascode" localize="false" id="N0428">Public Property Get SharedScripts() As String</paragraph> + <paragraph role="bascode" localize="false" id="N0429"> Dim inst As String, shr As String</paragraph> + <paragraph role="bascode" localize="false" id="N0430"> inst = ConvertFromURL(_ps.getSubstituteVariableValue("$(prog)"))</paragraph> + <paragraph role="bascode" localize="false" id="N0431"> shr = Tools.Strings.ReplaceString(inst,"Share","program")</paragraph> + <paragraph role="bascode" localize="false" id="N0432"> SharedScripts = shr & GetPathSeparator() &"Scripts"</paragraph> + <paragraph role="bascode" localize="false" id="N0433">End Property ' Session.sharedScripts</paragraph> + <paragraph role="bascode" localize="false" id="N0434"> </paragraph> + <paragraph role="bascode" localize="false" id="N0435">Public Property Get SharedPythonScripts() As String</paragraph> + <paragraph role="bascode" localize="false" id="N0436"> sharedPythonScripts = sharedScripts() & GetPathSeparator() &"python"</paragraph> + <paragraph role="bascode" localize="false" id="N0437">End Property ' Session.sharedPythonScripts</paragraph> + <paragraph role="bascode" localize="false" id="N0438"> </paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0439">Public Property Get UserName() As String ' User account name </paragraph> + <paragraph role="bascode" localize="false" id="N0440"> userName = _ps.getSubstituteVariableValue("$(username)")</paragraph> + <paragraph role="bascode" localize="false" id="N0441">End Property ' Session.userName</paragraph> + <paragraph role="bascode" localize="false" id="N0442"> </paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0443">Public Property Get UserProfile() As String ' User profile system path</paragraph> + <paragraph role="bascode" localize="false" id="N0444"> userProfile = ConvertFromURL(_ps.getSubstituteVariableValue("$(user)"))</paragraph> + <paragraph role="bascode" localize="false" id="N0445">End Property ' Session.userProfile</paragraph> + <paragraph role="bascode" localize="false" id="N0446"> </paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0447">Public Property Get UserScripts() As String ' User scripts system path</paragraph> + <paragraph role="bascode" localize="false" id="N0448"> userScripts = userProfile() & GetPathSeparator() &"Scripts"</paragraph> + <paragraph role="bascode" localize="false" id="N0449">End Property ' Session.userScripts</paragraph> + <paragraph role="bascode" localize="false" id="N0450"> </paragraph> + <paragraph role="bascode" xml-lang="en-US" id="N0451">Public Property Get UserPythonScripts() As String ' User Python scripts system path</paragraph> + <paragraph role="bascode" localize="false" id="N0452"> userPythonScripts = userScripts() & GetPathSeparator() &"python"</paragraph> + <paragraph role="bascode" localize="false" id="N0453">End Property ' Session.userPythonScripts</paragraph> + </bascode> + <section id="relatedtopics"> + <embed href="text/sbasic/python/python_locations.xhp#pythonlocations1"/> + <embed href="text/sbasic/python/python_import.xhp#pythonimporth1"/> + <embed href="text/sbasic/python/python_screen.xhp#ioscreen"/> + <embed href="text/sbasic/python/python_examples.xhp#pythonexamples2"/> + </section> +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/python/python_shell.xhp b/helpcontent2/source/text/sbasic/python/python_shell.xhp new file mode 100644 index 000000000..0b724b88d --- /dev/null +++ b/helpcontent2/source/text/sbasic/python/python_shell.xhp @@ -0,0 +1,59 @@ +<?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="python_shell" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">Python Interactive Shell</title> + <filename>/text/sbasic/python/python_shell.xhp</filename> + </topic> + </meta> + <body> + <bookmark branch="index" id="N0117"> + <bookmark_value>Python console</bookmark_value> + <bookmark_value>Python Interactive Shell</bookmark_value> + </bookmark> + <section id="pythonshell"> + <paragraph role="heading" level="1" id="N0118"><variable id="pythonshell1"><link href="text/sbasic/python/python_shell.xhp" name="python shell">Running Python Interactive Console</link></variable></paragraph> + </section> + <paragraph role="paragraph" id="N0119">The Python interactive console, also known as Python interpreter or Python shell, provides programmers with a quick way to execute commands and try out and test code without creating a file. UNO objects introspection as well as %PRODUCTNAME Python modules documentation can be obtained from the terminal.</paragraph> + <paragraph role="heading" level="2" id="N0121">Using a Basic macro:</paragraph> + <bascode> + <paragraph role="bascode" id="N0122" localize="false">Sub interpreter_console</paragraph> + <paragraph role="bascode" id="N0123" localize="false"> ps = CreateUnoService("com.sun.star.util.PathSettings")</paragraph> + <paragraph role="bascode" id="N0124" localize="false"> install_path = ConvertFromURL(ps.Module)</paragraph> + <paragraph role="bascode" id="N0125" localize="false"> Shell( install_path + GetPathSeparator() + "python" )</paragraph> + <paragraph role="bascode" id="N0126" localize="false">End Sub</paragraph> + </bascode> + <paragraph role="heading" level="2" id="N0127">Using a Python macro:</paragraph> + <pycode> + <paragraph role="pycode" id="N0128" localize="false"># -*- coding: utf-8 -*-</paragraph> + <paragraph role="pycode" id="N0129" localize="false">from __future__ import unicode_literals</paragraph> + <paragraph role="pycode" id="N0130" localize="false"> </paragraph> + <paragraph role="pycode" id="N0131" localize="false">import uno, os, subprocess</paragraph> + <paragraph role="pycode" id="N0132" localize="false"> </paragraph> + <paragraph role="pycode" id="N0133" localize="false">def interpreter_console():</paragraph> + <paragraph role="pycode" id="N0134" localize="false"> ctx = XSCRIPTCONTEXT.getComponentContext()</paragraph> + <paragraph role="pycode" id="N0135" localize="false"> smgr = ctx.getServiceManager()</paragraph> + <paragraph role="pycode" id="N0136" localize="false"> ps = smgr.createInstanceWithContext("com.sun.star.util.PathSettings", ctx)</paragraph> + <paragraph role="pycode" id="N0137" localize="false"> install_path = uno.fileUrlToSystemPath(ps.Module)</paragraph> + <paragraph role="pycode" id="N0138" localize="false"> pgm = install_path + os.sep + "python" # Python shell/console path</paragraph> + <paragraph role="pycode" id="N0139" localize="false"> subprocess.Popen(pgm) # Start Python interactive Shell</paragraph> + <paragraph role="pycode" id="N0140" localize="false"> </paragraph> + </pycode> + <paragraph role="heading" level="2" id="N0141">Usage:</paragraph> + <paragraph role="paragraph" id="N0142"> + <image src="media/helpimg/python/python_shell.png" id="N0143"><alt id="N0144">Python Interactive Console</alt></image> + </paragraph> + <section id="relatedtopics"> + <embed href="text/sbasic/python/python_examples.xhp#pythonexamples2"/> + <embed href="text/sbasic/python/main0000.xhp#pythonscriptshelp"/> + </section> +</body> +</helpdocument> |