PythonScriptability



WORK IN PROGRESS => '''Please do not translate the page yet

Introduction
This chapter aims to :


 * describe how to use Python with OOo4Kids.
 * teach the basics through examples
 * provide code samples
 * provide the most known links and references

How things work
There are two existing ways to use Python:


 * Approach 1: Outside OOo -- from a remote UNO connection.
 * It is a quick and easy way to write and debug code.
 * Approach 2: Inside OOo -- as an installed component.
 * Is a great way to _deliver_ finished code to a user, and it will be our choice as described below.

A Python module may contain several scripts.

 def HelloPython: import uno

def HelloPython: # accessing XSCRIPTCONTEXT oDoc = XSCRIPTCONTEXT.getDocument

xText = oDoc.getText xTextRange = xText.getEnd # set the text height xTextRange.CharHeight = 12.0

# set the character background color (verify hexadecimal works ...) xTextRange.CharBackColor = CC00aa

# shows how to use group constant # CharUnderline receives a group constant xTextRange.CharUnderline = uno.getConstantByName("com.sun.star.awt.FontUnderline.WAVE")

# shows how to use enum with Python macro # CharPosture receives an enum xTextRange.CharPosture = uno.getConstantByName("com.sun.star.awt.FontSlant.ITALIC") # the text xTextRange.setString( "Hello World (in Python)" )

# FIXME :explain return None

Remarks:

 SomeType getSomeProperty void setSomeProperty(SomeType aValue)
 * Python interprets pairs of get and set methods at UNO objects as object properties if they follow this pattern:

Written differently :  Sometype anObject.getSomeProperty void    anObject.setSomeProperty(SomeType aValue)

Using these facilities some lines can be simplified:  xText = oDoc.Text xTextRange = xText.End xTextRange.String = "Hello World (in Python)" Service properties can be directly accessed in Python, no need to use  or.

Using the OpenOffice.org API from macros
Using Python, the macro accesses  using the global variable

oDoc = XSCRIPTCONTEXT.getDocument

Handling arguments passed to macros
Using Python: The arguments are passed as parameters of the called function.

Python is used through the PyUno bridge, who is basically provided by OpenOffice.org and OOo4Kids.

'''The use is extremely simple: you write a document in Python, using OpenOffice.org / OOo4Kids API. Open this document as a macro, and then, you extend OpenOffice.org / OOo4Kids possibilities.'''

State of the features of script languages supported by Python with OOo4Kids and OOoLight
The original array is inspired from the UNO Component Packaging description, presented differently. Every feature will be adapted to OOo4Kids and OOoLight.

Reminder : unlike Java Macros, Python macros are interpreted

Relevant features of Python macros:


 * Interpreted macros: YES
 * Typeless variables: YES
 * Getter/Setter: YES
 * Direct Property Access: YES
 * Script encryption => NO, because we do not manage encryption in OOoLight nor OOo4Kids (please prefer OpenOffice.org in this case)

Linux specific

 * Verify whether Python is installed on the system
 * Check the current version

Mac OS X specific
On Mac OS X, we use the system version of Python. this can cause trouble on Mac OS X 10.4, because only 2.3.5 version is available, and Apple will not upgrade. the result is some uncompatibilities, and the macros should care of that.

Windows specific
FIXME : test it ..

[FIXME] : solve the issue about the exact Python version used in every operating system (known issues on Mac OS X, works nicely on Linux).

[FIXME] : provide a list of basic tests, to verify everything is ok for a given platform

Choose your debugger
Remark : untested on windows

To observe the debug output, and waiting an integrated tool be implemented, it is expected to launch OOo4Kids in the terminal. The tool we'll propose to use is gdb, but another debugger (like DDD) might work too.

Find pythonscript.py

 * On Linux, it will be in path_to_OOo4Kids/basis-link/program

/Applications/OOo4Kids.app/Contents/basis-link/program
 * On Mac OS X, in case you installed OOo4Kids (or OOoLight ) in /Application, you should find pythonscript.py in

Modify the script

 * make the script writable (chmod ug+w pythonscript.py on Mac or Linux)


 * Line around 15, you'll have to comment the right line. In your editor, this should produce:

Before the change :  LogLevel.use = LogLevel.NONE               # production level
 * 1) Configuration
 * 1) LogLevel.use = LogLevel.ERROR              # for script developers
 * 2) LogLevel.use = LogLevel.DEBUG              # for script framework developers

After the change :  LogLevel.use = LogLevel.DEBUG              # for script framework developers
 * 1) Configuration
 * 2) LogLevel.use = LogLevel.NONE               # production level
 * 3) LogLevel.use = LogLevel.ERROR              # for script developers

Other Debug possibilities in pythonscript.py
 LOG_STDOUT = True                          # True, writes to stdout (difficult on windows) # False, writes to user/Scripts/python/log.txt ENABLE_EDIT_DIALOG=False                   # offers a minimal editor for editing.

Choose as you want.

Add debug mode to the PyUNO bridge
In pyuno/source/module/pyuno_module.cxx is another existing possibilities.


 * PYUNO_LOGLEVEL

 OUString str; if( bootstrapHandle.getFrom( USTR_ASCII( "PYUNO_LOGLEVEL" ), str ) ) {                                                                                                                    if( str.equalsAscii( "NONE" ) ) *pLevel = LogLevel::NONE; else if( str.equalsAscii( "CALL" ) ) *pLevel = LogLevel::CALL; else if( str.equalsAscii( "ARGS" ) ) *pLevel = LogLevel::ARGS; else {                                                                                                                    fprintf( stderr, "unknown loglevel %s\n",                                                                                  OUStringToOString( str, RTL_TEXTENCODING_UTF8 ).getStr ); }                                                                                                            }

and you can set the environment variable as follow :

export PYUNO_LOGLEVEL=ARGS

Other posibilities are : CALL, and NONE (default, when the environment variable is undefined)


 * PYUNO_LOGTARGET

 if( bootstrapHandle.getFrom( USTR_ASCII( "PYUNO_LOGTARGET" ), str ) ) {                                                                                                                    if( str.equalsAscii( "stdout" ) ) *ppFile = stdout; else if( str.equalsAscii( "stderr" ) ) ...

More info and other possibilities
=> Read pyuno/source/module/pyuno_module.cxx

Launch the debugger

 * Open a Terminal
 * launch OOo4Kids using gdb, either
 * either attach the soffice.bin process to gdb
 * or use
 * cd $PATH_TO_SOFFICE.BIN
 * gdb -q --args soffice.bin

Code Snippets
Code Snippets

Links
UNO Component Packaging