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.romede...@sfr.fr>
AuthorDate: Wed Jan 2 20:40:03 2019 -0200
Commit: Olivier Hallot <olivier.hal...@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.hal...@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>
_______________________________________________
Libreoffice-commits mailing list
libreoffice-comm...@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/libreoffice-commits
