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
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.
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
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).|