Difference between revisions of "Documentation/DevGuide/ProUNO/Bridge/Automation Bridge"

Revision as of 15:02, 8 May 2008

The OpenOffice.org 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 OpenOffice.org 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. OpenOffice.org 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 OpenOffice.org. 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 OpenOffice.org 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 OpenOffice.org 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 OpenOffice.org functionality through Automation. Note the inline comments. The only automation specific call is WScript.CreateObject() in the first line, the remaining are OpenOffice.org 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 OpenOffice.org objects available to the programmer.