Automation Bridge

OpenOffice.org Developer's Guide

Professional UNO

< Previous Section

Next Section >

• Introduction
• API Concepts

• Data Types

• Simple Types
• The Any Type
• Interfaces
• Services
• Structs
• Predefined Values
• Sequences
• Modules
• Exceptions
• Singletons

• Understanding the API Reference

• UNO Concepts

• UNO Interprocess Connections

• Starting OpenOffice.org in Listening Mode
• Importing a UNO Object
• Characteristics of the Interprocess Bridge
• Opening a Connection
• Creating the Bridge
• Closing a Connection
• Example: A Connection Aware Client

• Service Manager and Component Context

• Service Manager
• Component Context

• Using UNO Interfaces
• Properties
• Collections and Containers
• Event Model
• Exception Handling
• Lifetime of UNO objects

• acquire() and release()
• The XComponent Interface
• Children of the XEventListener Interface
• Weak Objects and References
• Differences Between the Lifetime of C++ and Java Objects

• Object Identity

• UNO Language Bindings

• Java Language Binding

• Getting a Service Manager
• Transparent Use of Office UNO Components
• Handling Interfaces
• Type Mappings

• Mapping of Sequence Types
• Mapping of Enum Types
• Mapping of Struct Types
• Mapping of Exception Types
• Mapping of Interface Types
• Mapping of UNOIDL
• Mapping of Services
• Mapping of Singletons
• Inexact approximation of UNO Value Semantics

• C++ Language Binding

• Establishing Interprocess Connections
• Transparent Use of Office UNO Components
• Type Mappings

• Mapping of Struct Types
• Mapping of Interface Types
• Mapping of Sequence Types
• Mapping of Services
• Mapping of Singletons

• Using Weak References
• Exception Handling in C++

• OpenOffice.org Basic

• Handling UNO Objects

• Instantiating UNO Services
• Getting Information about UNO Objects

• Mapping of UNO and Basic Types

• Mapping of Simple Types
• Mapping of Sequences and Arrays
• Mapping of Structs
• Mapping of Enums and Constant Groups

• Case Sensitivity
• Exception Handling
• Listeners

• Automation Bridge

• The Service Manager Component
• Using UNO from Automation

• Calling Functions and Accessing Properties
• Return Values
• Usage of Types

• Using Automation Objects from UNO
• Type Mappings

• Default Mappings

• Mapping of Simple Types
• Mapping of Hyper and Decimal
• Mapping of String
• Mapping of Interfaces and Structures
• Mapping of Sequence
• Mapping of Type

• Conversion Mappings
• Client-Side Conversions
• Value Objects
• Exceptions and Errorcodes

• Automation Objects with UNO Interfaces
• DCOM
• The Bridge Services
• Unsupported COM Features

• CLI Language Binding

• The Language Binding DLLs
• Type Mapping

• Type Name Decoration
• Type Mappings
• Additional Structures

• Lifetime Management and Obtaining Interfaces
• Writing Client Programs

• The Override Problem
• Important Interfaces and Implementations

< Previous Page

Next Page >

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