mirror of
https://github.com/LibreOffice/help.git
synced 2026-01-13 05:38:56 +00:00
7e42394ecb
Replacement done with
find . -name \*.xhp -print0 |xargs -0 -P 0 perl -CS -pi -e \
's#(<link[^>]*?) +name *="[^"]*" *( [^>]+|) *>#$1$2>#g'
(note some inconsistencies with space between name and = and also having
empty value, and some more complicated expression to also clear up
double space before/after the attribute)
translation files will be prepped with:
find */helpcontent2 -name \*.po -print0 |xargs -0 -P 0 perl -CS -pi -e \
$'s#(<link[^>]*?) +name=(?:\\\\"[^"]*\\\\"|\'[^\']*\') *( [^>]+|) *(/?>)#$1$2$3#g unless /^#/'
(note that not all languages use the " as quote character for the
attributes, but that also single quotes appera in the po file. Hence
the use of the shell $'string' syntax to be able to quote ' as \'
It also requires to quote the backslash, so that it needs to be escaped
once for the shell, then another time for perl. Also don't work on
obsolete strings (those are prefixed with #~ in the po files)
Also note that <link..></link> gets turned into <link ../> during
translation extraction (along with removal of the space between the
attribute name and the value), so the pattern needs to be slightly
different here)
Change-Id: I95e53a08e6b0095cd894109ea0de154cc4859d8f
Reviewed-on: https://gerrit.libreoffice.org/c/help/+/143713
Tested-by: Jenkins
Reviewed-by: Christian Lohmaier <lohmaier+LibreOffice@googlemail.com>
339 lines
20 KiB
XML
339 lines
20 KiB
XML
<?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>XSCRIPTCONTEXT;getComponentContext</bookmark_value>
|
|
<bookmark_value>XSCRIPTCONTEXT;getDesktop</bookmark_value>
|
|
<bookmark_value>XSCRIPTCONTEXT;getDocument</bookmark_value>
|
|
<bookmark_value>uno.py;getComponentContext</bookmark_value>
|
|
<bookmark_value>uno.py;getDesktop</bookmark_value>
|
|
<bookmark_value>uno.py;getDocument</bookmark_value>
|
|
</bookmark>
|
|
<section id="pythonprogramming">
|
|
<h1 id="hd_id691546462755220"><variable id="pythonprogrammingheading"><link href="text/sbasic/python/python_programming.xhp">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">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">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">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>
|
|
<section id="uno">
|
|
<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">Python interactive shell</link> to get a complete module description using <literal>dir()</literal> and <literal>help()</literal> Python commands.</paragraph>
|
|
<bookmark xml-lang="en-US" branch="index" id="bm_id391659034206678">
|
|
<bookmark_value>uno.py</bookmark_value>
|
|
<bookmark_value>uno.py;absolutize</bookmark_value>
|
|
<bookmark_value>uno.py;createUnoStruct</bookmark_value>
|
|
<bookmark_value>uno.py;fileUrlToSystemPath</bookmark_value>
|
|
<bookmark_value>uno.py;getClass</bookmark_value>
|
|
<bookmark_value>uno.py;getComponentContext</bookmark_value>
|
|
<bookmark_value>uno.py;Enum</bookmark_value>
|
|
<bookmark_value>uno.py;getConstantByName</bookmark_value>
|
|
<bookmark_value>uno.py;isInterface</bookmark_value>
|
|
<bookmark_value>uno.py;systemPathToFileUrl</bookmark_value>
|
|
</bookmark>
|
|
<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>
|
|
</section>
|
|
<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">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">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="N1244">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="N2298">desktop = smgr.createInstanceWithContext(DESK , ctx)</paragraph>
|
|
<paragraph role="tablecontent" localize="false" id="N1299">doc = desktop.CurrentComponent</paragraph>
|
|
</tablecell>
|
|
<tablecell>
|
|
<paragraph role="tablecontent" localize="false" id="N1301">ThisComponent</paragraph>
|
|
</tablecell>
|
|
</tablerow>
|
|
</table>
|
|
<h2 id="N1297">Importing an embedded Module</h2>
|
|
<section id="PythonEmbeddedImport" >
|
|
<paragraph role="paragraph" id="N1298">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/">%PRODUCTNAME Application Programming Interface</link> (API) or download <link href="https://www.libreoffice.org/download/download/">%PRODUCTNAME Software Development Kit</link> (SDK).</paragraph>
|
|
<paragraph role="paragraph" id="N3299">Importing a Python document embedded module is illustrated below, exception handling is not detailed:</paragraph>
|
|
<pycode>
|
|
<paragraph role="pycode" localize="false" id="N1300">import uno, sys</paragraph>
|
|
<paragraph role="pycode" localize="false" id="N3301"></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="N1314"></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">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>
|