English:

The Free and Open Productivity Suite
Help us Help the World
Pyuno supports the OOo scripting framework, that is first shipped with OOo 2.0 (precisely since OOo 1.9.m79 or OOo 2.0 beta). The current support is limited to the 'core' framework, meaning that execution and assigning of macros via the standard Tools/Macro dialog works fine, but editing and debugging macros is not integrated in OpenOffice.org's UI (simply because of the lack of development resources). Use your favourite text editor to create and modify python scripts.

Script locations

Scripts to be excuted in OpenOffice.org can be stored within the following locations:

Script coding

A python script within the OpenOffice.org's scripting framework is a function (introduced by the def keyword) within a .py file. For execution via the Tools/Macros/Run macro dialog, the script must have an empty argument list. For typical event listeners, the function must have exactly one argument (the event). In general, the number of arguments depend on the context where the function shall be used. Since OOo 2.4, you can use both unix and windows linefeeds, in earlier versions you must use use unix line feeds.

A single .py file may contain an arbitrary number of function definitions. By default, all function definitions are exported ( = shown in the macro selection dialog). As this may become tedious, exports can be limited to a smaller set of functions by having a global variable named g_exportedScripts, which is a tuple of function definitions.

Up to OOo2.4, .py files can only import python modules, which are within the python PYTHONPATH, by default this is just the python runtime and the uno bridge files. This means, that it cannot reference other python macro files. Since OOo2.4, you can use the mechanism described here. Note that the main script file is reloaded after every change while the source files in PYHTHONPATH get loaded only once and changes won't have any effect until office restart.

Before executing the source code within the module, the global variable XSCRIPTCONTEXT is inserted as global variable within the module (this variable also exists e.g. for javascript and beanshell, it is offered here for consistency reasons). It has three members (Document,Desktop and ComponentContext).

The comment of a function (introduced and ended by three ") is shown as description in the macros' selection dialog.

The compiled python script files are not added to sys.modules. There may exist multiple instances of the same module at the same time.

Example:

# HelloWorld python script for the scripting framework

def HelloWorldPython( ):
    """Prints the string 'Hello World(in Python)' into the current document"""
    #get the doc from the scripting context which is made available to all scripts
    model = XSCRIPTCONTEXT.getDocument()
    text = model.Text
    cursor = text.createTextCursor()
    text.insertString( cursor, "Hello World(in Python)", 0 )

Error handling and debugging

Errors during compilation or execution of the scripts are passed as exceptions to the scripting framework where possible. The scripting framework in general opens a popup box and displays the message of the thrown exception.

However, sometimes this is not possible and an error gets silently ignored. The user realizes these errors, when

You can get to know these problems by changing some flags in the OpenOffice.org 2.0/program/pythonscript.py file :
# Configuration ----------------------------------------------------
LogLevel.use = LogLevel.NONE                # alternavly use LogLevel.ERROR or LogLevel.DEBUG
LOG_STDOUT = False                          # True, writes to stdout
                                            # False, writes to user/Scripts/python/log.txt
ENABLE_EDIT_DIALOG=False                    # offers a minimal editor for editing.

Attaching a python debugger is currently not supported.

Credits

The python binding of the scripting framework is developed and maintained by Joerg Budischewski in his spare time. Many, many thanks to Tomas O'Connor from Sun for his great support and his code additions to the framework which made this binding possible. Please put low level questions about the binding to dev@udk.openoffice.org. Questions about the OpenOffice.org's API should be put to dev@api.openoffice.org.

License

This document is available under PDL (Public Documentation License).

Logo ApacheCon Europe 2014

Apache Feather

Copyright & License | Privacy | Website Feedback | Contact Us | Donate | Thanks

Apache, the Apache feather logo, and OpenOffice are trademarks of The Apache Software Foundation. OpenOffice.org and the seagull logo are registered trademarks of The Apache Software Foundation. Other names appearing on the site may be trademarks of their respective owners.