PythonScriptability
Extend OOo4Kids using Python
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:
- Python interprets pairs of get and set methods at UNO objects as object properties if they follow this pattern:
SomeType getSomeProperty() void setSomeProperty(SomeType aValue)
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 getPropertyValue or setPropertyValue.
Using the OpenOffice.org API from macros
Using Python, the macro accesses XScriptContext using the global variable XSCRIPTCONTEXT
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)
| Feature | State | Devs | Testers | Estimated ETA | Comments (keywords + links) | Related issues (issues list + links) | Documentation (YES -links- or NO) | Integrated (YES, devel, NO) |
|---|---|---|---|---|---|---|---|---|
| Integrated editor | 
|
x | x | x | x | x | x | x |
| Script Organizer |
|
x | x | x | x | x | x | x |
| Integrated debugger |
|
x | x | x | x | x | x | x |
| Function for Calc Formula |
|
x | x | x | x | x | x | x |
| Write examples |
|
x | x | x | x | x | x | x |
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
Code sample
Debug mode
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.
Change for the debug mode
Find pythonscript.py
- On Linux, it will be in path_to_OOo4Kids/basis-link/program
- On Mac OS X, in case you installed OOo4Kids (or OOoLight ) in /Application, you should find pythonscript.py in
/Applications/OOo4Kids.app/Contents/basis-link/program
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 :
# Configuration ---------------------------------------------------- LogLevel.use = LogLevel.NONE # production level #LogLevel.use = LogLevel.ERROR # for script developers #LogLevel.use = LogLevel.DEBUG # for script framework developers
After the change :
# Configuration ---------------------------------------------------- #LogLevel.use = LogLevel.NONE # production level #LogLevel.use = LogLevel.ERROR # for script developers LogLevel.use = LogLevel.DEBUG # for script framework 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
