Difference between revisions of "PyUNO bridge"
(→PyUNO bridge modes) |
|||
Line 28: | Line 28: | ||
PyUNO can be used in three different modes: | PyUNO can be used in three different modes: | ||
* Inside the OpenOffice.org process within the scripting framework (OOo 2.0 and later only !!), | * Inside the OpenOffice.org process within the scripting framework (OOo 2.0 and later only !!), | ||
− | * Inside the python executable (and outside the OOo process) | + | * Inside the python executable (and outside the OOo process)[http://udk.openoffice.org/python/images/mode_ipc.png] |
+ | |||
+ | Use this mode, when you | ||
+ | * begin to use PyUNO (as it is the more intuitive approach). | ||
+ | * want to trigger script execution by starting a separate process (e.g. a cgi-script within a http-server). | ||
+ | * want the shortest turnaround times (code - execute - code - execute ...) | ||
+ | |||
+ | =====Hello World ===== | ||
+ | |||
+ | Make sure, that OpenOffice.org is not running (note that on windows you must also terminate the quick starter in the system tray at the right bottom of your desktop). Start a system shell ( cmd on Win NT/2000/XP, command on Win9x, tcsh or bash on Unix). Switch to the Office program directory (e.g. C:\Program Files\OpenOffice.org1.1\program ) and start the office with the following command line parameters | ||
+ | |||
+ | c:\Program Files\OpenOffice1.1\program> soffice "-accept=socket,host=localhost,port=2002;urp;" | ||
+ | |||
+ | Now use your favourite text editor to create the following hello_world.py sample program: | ||
+ | |||
+ | <code>[python]import uno | ||
+ | |||
+ | # get the uno component context from the PyUNO runtime | ||
+ | localContext = uno.getComponentContext() | ||
+ | |||
+ | # create the UnoUrlResolver | ||
+ | resolver = localContext.ServiceManager.createInstanceWithContext( | ||
+ | "com.sun.star.bridge.UnoUrlResolver", localContext ) | ||
+ | |||
+ | # connect to the running office | ||
+ | ctx = resolver.resolve( "uno:socket,host=localhost,port=2002;urp;StarOffice.ComponentContext" ) | ||
+ | smgr = ctx.ServiceManager | ||
+ | |||
+ | # get the central desktop object | ||
+ | desktop = smgr.createInstanceWithContext( "com.sun.star.frame.Desktop",ctx) | ||
+ | |||
+ | # access the current writer document | ||
+ | model = desktop.getCurrentComponent() | ||
+ | |||
+ | # access the document's text property | ||
+ | text = model.Text | ||
+ | |||
+ | # create a cursor | ||
+ | cursor = text.createTextCursor() | ||
+ | |||
+ | # insert the text into the document | ||
+ | text.insertString( cursor, "Hello World", 0 ) | ||
+ | |||
+ | # Do a nasty thing before exiting the python process. In case the | ||
+ | # last call is a oneway call (e.g. see idl-spec of insertString), | ||
+ | # it must be forced out of the remote-bridge caches before python | ||
+ | # exits the process. Otherwise, the oneway call may or may not reach | ||
+ | # the target object. | ||
+ | # I do this here by calling a cheap synchronous call (getPropertyValue). | ||
+ | ctx.ServiceManager | ||
+ | </code> | ||
+ | |||
+ | Now start the above script with the python script located in the program directory | ||
+ | |||
+ | c:\Program Files\OpenOffice1.1\program> .\python hello_world.py | ||
+ | |||
+ | Note: You must use the script/batch file in the program directory to start python, simply starting the python executable in the runtime directory (or from python installation installed somewhere else on your machine) will not work. | ||
+ | |||
+ | This scripts prints "Hello World" into the current writer document. |
Revision as of 22:34, 21 December 2006
Contents
Translations
Find here a shortened Spanish version of this document.
Introduction
The Python-UNO bridge allows to
- use the standard OpenOffice.org API from the well known python scripting language.
- to develop UNO components in python, thus python UNO components may be run within the OpenOffice.org process and can be called from Java, C++ or the built in StarBasic scripting language.
- create and invoke scripts with the office scripting framework (OOo 2.0 and later).
You can find the most current version of this document from http://udk.openoffice.org/python/python-bridge.html
Download
You can also download this documentation for offline work.
Download pyuno-doc.zip ( less than 0.5 MB).
State
The Python-UNO bridge is feature complete, but has not been used extensively, so it may contain some bugs. It is now integrated in the OpenOffice.org source trees. (OpenOffice.org 1.0.x is not supported.)
The documentation in its current state is targeted at developers who have already some experience with OpenOffice.org API and with some other programming language (Java/C++/StarBasic). It is recommended that you read that some background information from the developer manual before looking at the specifics of python.
PyUNO tutorial for OpenOffice.org
This tutorial shows, how the PyUNO bridge can be used to automate OpenOffice.org. This is not an OpenOffice.org tutorial, there is lots of resources available in the office development kit and the developer manual.
PyUNO Installation
Since OpenOffice.org 1.1, PyUNO is included in the default installation.
PyUNO bridge modes
PyUNO can be used in three different modes:
- Inside the OpenOffice.org process within the scripting framework (OOo 2.0 and later only !!),
- Inside the python executable (and outside the OOo process)[1]
Use this mode, when you
- begin to use PyUNO (as it is the more intuitive approach).
- want to trigger script execution by starting a separate process (e.g. a cgi-script within a http-server).
- want the shortest turnaround times (code - execute - code - execute ...)
Hello World
Make sure, that OpenOffice.org is not running (note that on windows you must also terminate the quick starter in the system tray at the right bottom of your desktop). Start a system shell ( cmd on Win NT/2000/XP, command on Win9x, tcsh or bash on Unix). Switch to the Office program directory (e.g. C:\Program Files\OpenOffice.org1.1\program ) and start the office with the following command line parameters
c:\Program Files\OpenOffice1.1\program> soffice "-accept=socket,host=localhost,port=2002;urp;"
Now use your favourite text editor to create the following hello_world.py sample program:
[python]import uno
- get the uno component context from the PyUNO runtime
localContext = uno.getComponentContext()
- create the UnoUrlResolver
resolver = localContext.ServiceManager.createInstanceWithContext( "com.sun.star.bridge.UnoUrlResolver", localContext )
- connect to the running office
ctx = resolver.resolve( "uno:socket,host=localhost,port=2002;urp;StarOffice.ComponentContext" ) smgr = ctx.ServiceManager
- get the central desktop object
desktop = smgr.createInstanceWithContext( "com.sun.star.frame.Desktop",ctx)
- access the current writer document
model = desktop.getCurrentComponent()
- access the document's text property
text = model.Text
- create a cursor
cursor = text.createTextCursor()
- insert the text into the document
text.insertString( cursor, "Hello World", 0 )
- Do a nasty thing before exiting the python process. In case the
- last call is a oneway call (e.g. see idl-spec of insertString),
- it must be forced out of the remote-bridge caches before python
- exits the process. Otherwise, the oneway call may or may not reach
- the target object.
- I do this here by calling a cheap synchronous call (getPropertyValue).
ctx.ServiceManager
Now start the above script with the python script located in the program directory
c:\Program Files\OpenOffice1.1\program> .\python hello_world.py
Note: You must use the script/batch file in the program directory to start python, simply starting the python executable in the runtime directory (or from python installation installed somewhere else on your machine) will not work.
This scripts prints "Hello World" into the current writer document.