[Libreoffice-commits] help.git: AllLangHelp_sbasic.mk source/text
Libreoffice Gerrit user
logerrit at kemper.freedesktop.org
Thu Jan 3 10:45:27 UTC 2019
AllLangHelp_sbasic.mk | 1
source/text/sbasic/python/main0000.xhp | 5
source/text/sbasic/python/python_programming.xhp | 292 +++++++++++++++++++++++
3 files changed, 295 insertions(+), 3 deletions(-)
New commits:
commit 4df68585db8f4c74a1d74c6d7bc97bfb0c18f36f
Author: Alain Romedenne <pyoffice.romedenne at sfr.fr>
AuthorDate: Wed Jan 2 20:40:03 2019 -0200
Commit: Olivier Hallot <olivier.hallot at libreoffice.org>
CommitDate: Thu Jan 3 11:45:06 2019 +0100
tdf#121736 Python programming Help pages
Change-Id: I6307a9f5e5ae27931ca12d8268d825afcee58539
Reviewed-on: https://gerrit.libreoffice.org/65828
Tested-by: Jenkins
Reviewed-by: Olivier Hallot <olivier.hallot at libreoffice.org>
diff --git a/AllLangHelp_sbasic.mk b/AllLangHelp_sbasic.mk
index f9b8f4b93..61a7fa5d9 100644
--- a/AllLangHelp_sbasic.mk
+++ b/AllLangHelp_sbasic.mk
@@ -368,6 +368,7 @@ $(eval $(call gb_AllLangHelp_add_helpfiles,sbasic,\
helpcontent2/source/text/sbasic/python/main0000 \
helpcontent2/source/text/sbasic/python/python_ide \
helpcontent2/source/text/sbasic/python/python_locations \
+ helpcontent2/source/text/sbasic/python/python_programming \
helpcontent2/source/text/sbasic/python/python_shell \
))
diff --git a/source/text/sbasic/python/main0000.xhp b/source/text/sbasic/python/main0000.xhp
index cd2cbf935..05f9abcc9 100644
--- a/source/text/sbasic/python/main0000.xhp
+++ b/source/text/sbasic/python/main0000.xhp
@@ -27,13 +27,12 @@
<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>
<embed href="text/shared/need_help.xhp#needhelp"/>
- <h2 id="hd_id3146957">Working with Python Scripts in %PRODUCTNAME.</h2>
+ <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 Python interactive console from %PRODUCTNAME .</paragraph>
<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"/>
- <paragraph role="paragraph" id="par_id551543347858350" xml-lang="en-US">Programming with Python Scripts
- </paragraph>
+ <embed href="text/sbasic/python/python_programming.xhp#pythonprogrammingheading"/>
<paragraph role="paragraph" id="par_id861543347870798" xml-lang="en-US">Creating a dialog</paragraph>
<paragraph role="paragraph" id="par_id71543347877088" xml-lang="en-US">Programming Examples</paragraph>
<embed href="text/swriter/main0000.xhp#helpabouthelp"/>
diff --git a/source/text/sbasic/python/python_programming.xhp b/source/text/sbasic/python/python_programming.xhp
new file mode 100644
index 000000000..46d9d90c1
--- /dev/null
+++ b/source/text/sbasic/python/python_programming.xhp
@@ -0,0 +1,292 @@
+<?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 ="external">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 ="external">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 ="external">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 ="external">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 = ..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" localize="false" id="N0281">ctx = ..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" id="N0284">See Creating a Dialog</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph role="tablecontent" localize="false" id="N0285">CreateUnoDialog()</paragraph>
+ </tablecell>
+ </tablerow>
+ <tablerow>
+ <tablecell>
+ <paragraph role="tablecontent" id="N0286">See Creating a Listener</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>
+ </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>
+ </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 ="external">%PRODUCTNAME Application Programming Interface</link> (API) or download <link href="https://www.libreoffice.org/download/download/" name ="external">%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) # doc 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 ="external">Basic UNO Objects, Functions and Services</link></paragraph>
+ <paragraph role="paragraph" id="N0322"><link href="text/sbasic/python/python_import.xhp" name ="external">Importing Modules</link></paragraph>
+ <paragraph role="paragraph" id="N0323"><link href="text/sbasic/python/python_screen.xhp" name ="external">Input/Output to Screen</link></paragraph>
+ </section>
+</body>
+</helpdocument>
More information about the Libreoffice-commits
mailing list