diff --git a/AllLangHelp_sbasic.mk b/AllLangHelp_sbasic.mk index f9b8f4b935..61a7fa5d9b 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 cd2cbf9359..05f9abcc9e 100644 --- a/source/text/sbasic/python/main0000.xhp +++ b/source/text/sbasic/python/main0000.xhp @@ -27,13 +27,12 @@ This help section explains the most common Python script functions for %PRODUCTNAME. For more in-depth information please refer to the Designing & Developing Python Applications on the Wiki. -

Working with Python Scripts in %PRODUCTNAME.

+

Working with Python Scripts in %PRODUCTNAME

You can execute Python scripts choosing Tools - Macros – Run macro.... 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 . - Programming with Python Scripts - + Creating a dialog Programming Examples diff --git a/source/text/sbasic/python/python_programming.xhp b/source/text/sbasic/python/python_programming.xhp new file mode 100644 index 0000000000..46d9d90c19 --- /dev/null +++ b/source/text/sbasic/python/python_programming.xhp @@ -0,0 +1,292 @@ + + + + + + Python : Programming with Python + /text/sbasic/python/python_programming.xhp + + + + + Python;Programming + XSCRIPTCONTEXT;Python + uno.py + +
+

Programming with Python Scripts

+
+ A Python macro is a function within a .py file, identified as a module. Unlike %PRODUCTNAME Basic and its dozen of UNO objects functions or services, Python macros use the XSCRIPTCONTEXT UNO single object, shared with JavaScript and Beanshell. The g_exportedScripts global tuple explicitly lists selectable macros from a module. Python modules hold autonomous code logic, and are independent from one another. +

XSCRIPTCONTEXT Global Variable

+ Genuine Basic UNO facilities can be inferred from XSCRIPTCONTEXT global variable. Refer to %PRODUCTNAME API for a complete description of XSCRIPTCONTEXT. XSCRIPTCONTEXT methods summarize as: + + + + Methods + + + Description + + + Mapped in Basic as + + + + + getDocument() + + + The document reference on which the script can operate. + + + ThisComponent + + + + + getDesktop() + + + The desktop reference on which the script can operate. + + + StarDesktop + + + + + getComponentContext() + + + The component context which the script can use to create other uno components. + + + GetDefaultContext + + +
+ HelloWorld and Capitalise installation shared scripts illustrate UNO-related macros making use of XSCRIPTCONTEXT global variable. + Python standard output file is not available when running Python macros from Tools - Macros - Run Macro menu. Refer to Input/Output to Screen for more information. +

Module import

+ XSCRIPTCONTEXT is not provided to imported modules. +
+ %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 My macros within <User Profile>/Scripts/python/pythonpath. Python libraries help organize modules in order to prevent module name collisions. Import uno.py inside shared modules. +
+ Genuine BASIC UNO facilities can be inferred using uno.py module. Use Python interactive shell to get a complete module description using dir() and help() Python commands. + + + + Functions + + + Description + + + Mapped in Basic as + + + + + absolutize() + + + Returns an absolute file url from the given urls. + + + + + + + createUnoStruct() + + + Creates a UNO struct or exception given by typeName. + + + CreateUNOStruct() + + + + + fileUrlToSystemPath() + + + Returns a system path. + + + ConvertFromURL() + + + + + getClass() + + + Returns the class of a concrete UNO exception, struct, or interface. + + + + + + + getComponentContext() + + + Returns the UNO component context used to initialize the Python runtime. + + + GetDefaultContext() + + + + + Enum() + getConstantByName() + + + Looks up the value of an IDL constant by giving its explicit name. + + + See API constant groups + + + + + isInterface() + + + Returns True, when obj is a class of a UNO interface. + + + + + + + systemPathToFileUrl() + + + Returns a file URL for the given system path. + + + ConvertToURL() + + +
+ LibreLogo and TableSample installation shared scripts use uno.py module. +

More Python-Basic samples

+ + + + Python UNO + + + Basic UNO features + + + + + ctx = ..getComponentContext() + smgr = ctx.getServiceManager() + obj = smgr.createInstanceWithContext( .. , ctx) + + + CreateUnoService() + + + + + ctx = ..getComponentContext() + smgr = ctx.getServiceManager() + + + GetProcessServiceManager() + + + + + See Creating a Dialog + + + CreateUnoDialog() + + + + + See Creating a Listener + + + CreateUnoListener() + + + + + See UNO data types + + + CreateUnoValue() + CreateObject() + + + + + + + EqualUnoObjects() + + + + + + + HasUnoInterfaces() + + + + + + + IsUnoStruct() + + +
+

Importing an embedded Module

+
+ 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 %PRODUCTNAME Application Programming Interface (API) or download %PRODUCTNAME Software Development Kit (SDK). + Importing a Python document embedded module is illustrated below, exception handling is not detailed: + + import uno, sys + + def load_library(library_name: str, module_name=None): + """ load library and import module + + Adapted from 'Bibliothèque de fonctions' by Hubert Lambert + at https://forum.openoffice.org/fr/forum/viewtopic.php?p=286213""" + doc = XSCRIPTCONTEXT.getDocument() # current document + url = uno.fileUrlToSystemPath('{}/{}/{}', \ + format(doc.URL, 'Scripts/python', library_name) # ConvertToURL() + if not url in sys.path: # add path if necessary + sys.path.insert(0, url) # doc takes precedence + if module_name: # import if requested + return zipimport.zipimporter(url).load_module(module_name) + + def import_embedded_python(): + ui = load_library("my_gui",'screen_io') # add <lib> path + import <module> + ui.MsgBox(sys.modules.keys()) + + g_exportedScripts = import_embedded_python, # Public macros + +
+
+ Basic UNO Objects, Functions and Services + Importing Modules + Input/Output to Screen +
+ +