Automation Bridge

From Apache OpenOffice Wiki
Jump to: navigation, search

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.


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("")
  'Create the CoreReflection service that is later used to create structs
  Set objCoreReflection= objServiceManager.createInstance("")
  'Create the Desktop
  Set objDesktop= objServiceManager.createInstance("")
  '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( "")
  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("")
  'Create a Size struct.
  Set objSize= createStruct("") '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.", _
  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 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).
Personal tools
In other languages