Automation Bridge
The Apache OpenOffice software supports Microsoft's Automation technology. This offers programmers the possibility to control the office from external programs. There is a range of efficient IDEs and tools available for developers to choose from.
Automation is language independent. The respective compilers or interpreters must, however, support Automation. The compilers transform the source code into Automation compatible computing instructions. For example, the string and array types of your language can be used without caring about their internal representation in Automation, which is BSTR and SAFEARRAY. A client program that controls Apache OpenOffice can be represented by an executable (Visual Basic, C++) or a script (JScript, VB Script). The latter requires an additional program to run the scripts, such as Windows Scripting Host (WSH) or Internet Explorer.
UNO was not designed to be compatible with Automation and COM, although there are similarities. Apache OpenOffice deploys a bridging mechanism provided by the Automation Bridge to make UNO and Automation work together. The bridge consists of UNO services, however, it is not necessary to have a special knowledge about them to write Automation clients for Apache OpenOffice. For additional information, see The Bridge Services.
Different languages have different capabilities. There are differences in the manner that the same task is handled, depending on the language used. Examples in Visual Basic, VB Script and JScript are provided. They will show when a language requires special handling or has a quality to be aware of. Although Automation is supposed to work across languages, there are subtleties that require a particular treatment by the bridge or a style of coding. For example, JScript does not know out parameters, therefore Array objects have to be used. Currently, the bridge has been tested with C++, JScript, VBScript and Visual Basic, although other languages can be used as well.
The name Automation Bridge implies the use of the Automation technology. Automation is part of the collection of technologies commonly referred to as ActiveX or OLE, therefore the term OLE Bridge is misleading and should be avoided. Sometimes the bridge is called COM bridge, which is also wrong, since the only interfaces which are processed by the bridge are IUnknown and IDispatch.
Requirements
The Automation technology can only be used with Apache OpenOffice on a Windows platform (Windows 95, 98, NT4, ME, 2000, XP). There are COM implementations on Macintosh OS and UNIX, but there has been no effort to support Automation on these platforms.
Using Automation involves creating objects in a COM-like fashion, that is, using functions like CreateObject() in VB or CoCreateInstance() in C. This requires the Apache OpenOffice automation objects to be registered with the Windows system registry. This registration is carried out whenever an office is installed on the system. If the registration did not take place, for example because the binaries were just copied to a certain location, then Automation clients will not work correctly or not at all. Refer to The Service Manager Component for additional information.
A Quick Tour
The following example shows how to access Apache OpenOffice functionality through Automation. Note the inline comments. The only automation specific call is WScript.CreateObject() in the first line, the remaining are Apache OpenOffice API calls. The helper functions createStruct() and insertIntoCell() are shown at the end of the listing
'This is a VBScript example
'The service manager is always the starting point
'If there is no office running then an office is started up
Set objServiceManager= WScript.CreateObject("com.sun.star.ServiceManager")
'Create the CoreReflection service that is later used to create structs
Set objCoreReflection= objServiceManager.createInstance("com.sun.star.reflection.CoreReflection")
'Create the Desktop
Set objDesktop= objServiceManager.createInstance("com.sun.star.frame.Desktop")
'Open a new empty writer document
Dim args()
Set objDocument= objDesktop.loadComponentFromURL("private:factory/swriter", "_blank", 0, args)
'Create a text object
Set objText= objDocument.getText
'Create a cursor object
Set objCursor= objText.createTextCursor
'Inserting some Text
objText.insertString objCursor, "The first line in the newly created text document." & vbLf, false
'Inserting a second line
objText.insertString objCursor, "Now we're in the second line", false
'Create instance of a text table with 4 columns and 4 rows
Set objTable= objDocument.createInstance( "com.sun.star.text.TextTable")
objTable.initialize 4, 4
'Insert the table
objText.insertTextContent objCursor, objTable, false
'Get first row
Set objRows= objTable.getRows
Set objRow= objRows.getByIndex( 0)
'Set the table background color
objTable.setPropertyValue "BackTransparent", false
objTable.setPropertyValue "BackColor", 13421823
'Set a different background color for the first row
objRow.setPropertyValue "BackTransparent", false
objRow.setPropertyValue "BackColor", 6710932
'Fill the first table row
insertIntoCell "A1","FirstColumn", objTable 'insertIntoCell is a helper function, see below
insertIntoCell "B1","SecondColumn", objTable
insertIntoCell "C1","ThirdColumn", objTable
insertIntoCell "D1","SUM", objTable
objTable.getCellByName("A2").setValue 22.5
objTable.getCellByName("B2").setValue 5615.3
objTable.getCellByName("C2").setValue -2315.7
objTable.getCellByName("D2").setFormula"sum "
objTable.getCellByName("A3").setValue 21.5
objTable.getCellByName("B3").setValue 615.3
objTable.getCellByName("C3").setValue -315.7
objTable.getCellByName("D3").setFormula "sum "
objTable.getCellByName("A4").setValue 121.5
objTable.getCellByName("B4").setValue -615.3
objTable.getCellByName("C4").setValue 415.7
objTable.getCellByName("D4").setFormula "sum "
'Change the CharColor and add a Shadow
objCursor.setPropertyValue "CharColor", 255
objCursor.setPropertyValue "CharShadowed", true
'Create a paragraph break
'The second argument is a com::sun::star::text::ControlCharacter::PARAGRAPH_BREAK constant
objText.insertControlCharacter objCursor, 0 , false
'Inserting colored Text.
objText.insertString objCursor, " This is a colored Text - blue with shadow" & vbLf, false
'Create a paragraph break ( ControlCharacter::PARAGRAPH_BREAK).
objText.insertControlCharacter objCursor, 0, false
'Create a TextFrame.
Set objTextFrame= objDocument.createInstance("com.sun.star.text.TextFrame")
'Create a Size struct.
Set objSize= createStruct("com.sun.star.awt.Size") 'helper function, see below
objSize.Width= 15000
objSize.Height= 400
objTextFrame.setSize( objSize)
' TextContentAnchorType.AS_CHARACTER = 1
objTextFrame.setPropertyValue "AnchorType", 1
'insert the frame
objText.insertTextContent objCursor, objTextFrame, false
'Get the text object of the frame
Set objFrameText= objTextFrame.getText
'Create a cursor object
Set objFrameTextCursor= objFrameText.createTextCursor
'Inserting some Text
objFrameText.insertString objFrameTextCursor, "The first line in the newly created text frame.", _
false
objFrameText.insertString objFrameTextCursor, _
vbLf & "With this second line the height of the frame raises.", false
'Create a paragraph break
'The second argument is a com::sun::star::text::ControlCharacter::PARAGRAPH_BREAK constant
objFrameText.insertControlCharacter objCursor, 0 , false
'Change the CharColor and add a Shadow
objCursor.setPropertyValue "CharColor", 65536
objCursor.setPropertyValue "CharShadowed", false
'Insert another string
objText.insertString objCursor, " That's all for now !!", false
On Error Resume Next
If Err Then
MsgBox "An error occurred"
End If
Sub insertIntoCell( strCellName, strText, objTable)
Set objCellText= objTable.getCellByName( strCellName)
Set objCellCursor= objCellText.createTextCursor
objCellCursor.setPropertyValue "CharColor",16777215
objCellText.insertString objCellCursor, strText, false
End Sub
Function createStruct( strTypeName)
Set classSize= objCoreReflection.forName( strTypeName)
Dim aStruct
classSize.createObject aStruct
Set createStruct= aStruct
End Function
This script created a new document and started the office, if necessary. The script also wrote text, created and populated a table, used different background and pen colors. Only one object is created as an ActiveX component called com.sun.star.ServiceManager. The service manager is then used to create additional objects which in turn provided other objects. All those objects provide functionality that can be used by invoking the appropriate functions and properties. A developer must learn which objects provide the desired functionality and how to obtain them. The chapter First Steps introduces the main Apache OpenOffice objects available to the programmer.
| Content on this page is licensed under the Public Documentation License (PDL). |
