Developer's Guide - SVN - The Apache Software Foundation!

1250 Pages·2007·17.08 MB·English

by  Ralf Kuhnert

OpenOffice.org 2.3
Developer's Guide
June 2007
This documentation is distributed under licenses restricting its use. You may
make copies of and redistribute it, but you may not modify or make derivative
works of this documentation without prior written authorization of Sun and its
licensors, if any.
Copyright 2007 Sun Microsystems, Inc.
Contents
1 Reader's Guide 29
1.1 What This Manual Covers .......................................................................................................... 29
1.2 How This Book is Organized ...................................................................................................... 29
1.3 OpenOffice.org Version History ................................................................................................ 30
1.4 Related documentation ................................................................................................................ 30
1.5 Conventions .................................................................................................................................. 31
1.6 Acknowledgments ....................................................................................................................... 31
2 First Steps 33
2.1 Programming with UNO ............................................................................................................ 33
2.2 Fields of Application for UNO ................................................................................................... 33
2.3 Getting Started .............................................................................................................................. 34
2.3.1 Required Files .................................................................................................................. 34
2.3.2 Installation Sets ............................................................................................................... 34
2.3.3 Configuration .................................................................................................................. 35
Enable Java in OpenOffice.org ............................................................................... 35
Use Java UNO class files ......................................................................................... 35
Add the API Reference to your IDE ...................................................................... 35
2.3.4 First Contact .................................................................................................................... 36
Getting Started ......................................................................................................... 36
Service Managers ..................................................................................................... 38
Failed Connections .................................................................................................. 39
2.4 How to get Objects in OpenOffice.org ...................................................................................... 39
2.5 Working with Objects .................................................................................................................. 40
2.5.1 Objects, Interfaces, and Services ................................................................................... 41
Objects ....................................................................................................................... 41
Interfaces ................................................................................................................... 41
Services ...................................................................................................................... 41
2.5.2 Using Services ................................................................................................................. 43
Using Interfaces ........................................................................................................ 45
Using Properties ....................................................................................................... 47
2.5.3 Example: Working with a Spreadsheet Document .................................................... 47
2.5.4 Common Types ............................................................................................................... 48
Basic Types ................................................................................................................ 49
Strings ........................................................................................................................ 49
Enum Types and Groups of Constants ................................................................. 50
2.5.5 Struct ................................................................................................................................. 50
2.5.6 Any ................................................................................................................................... 51
2.5.7 Sequence ........................................................................................................................... 52
2.5.8 Element Access ................................................................................................................ 53
Name Access ............................................................................................................. 55
Index Access ............................................................................................................. 56
Enumeration Access ................................................................................................ 56
2.6 How do I know Which Type I Have? ........................................................................................ 57
2.7 Example: Hello Text, Hello Table, Hello Shape ....................................................................... 58
2.7.1 Common Mechanisms for Text, Tables and Drawings ............................................. 58
2.7.2 Creating Text, Tables and Drawing Shapes ................................................................ 63
Text, Tables and Drawings in Writer .................................................................... 63
Text, Tables and Drawings in Calc ........................................................................ 64
Drawings and Text in Draw ................................................................................... 65
3 Professional UNO 67
3.1 Introduction .................................................................................................................................. 67
3.2 API Concepts ................................................................................................................................ 68
3.2.1 Data Types ....................................................................................................................... 68
Simple Types ............................................................................................................ 68
The Any Type ........................................................................................................... 69
Interfaces ................................................................................................................... 69
Services ...................................................................................................................... 71
Structs ........................................................................................................................ 76
Predefined Values .................................................................................................... 77
Sequences .................................................................................................................. 78
Modules ..................................................................................................................... 78
Exceptions ................................................................................................................. 78
Singletons .................................................................................................................. 79
3.2.2 Understanding the API Reference ................................................................................ 79
Specification, Implementation and Instances ...................................................... 79
Object Composition ................................................................................................. 80
3.3 UNO Concepts .............................................................................................................................. 81
3.3.1 UNO Interprocess Connections .................................................................................... 81
Starting OpenOffice.org in Listening Mode ......................................................... 81
Importing a UNO Object ......................................................................................... 82
Characteristics of the Interprocess Bridge ............................................................ 83
Opening a Connection ............................................................................................. 84
Creating the Bridge .................................................................................................. 86
Closing a Connection ............................................................................................... 87
Example: A Connection Aware Client .................................................................. 88
3.3.2 Service Manager and Component Context ................................................................. 90
Service Manager ....................................................................................................... 90
Component Context ................................................................................................. 91
3.3.3 Using UNO Interfaces .................................................................................................... 94
3.3.4 Properties ......................................................................................................................... 97
3.3.5 Collections and Containers ......................................................................................... 101
3.3.6 Event Model .................................................................................................................. 104
3.3.7 Exception Handling ...................................................................................................... 104
User-Defined Exceptions ...................................................................................... 105
Runtime Exceptions ............................................................................................... 106
Good Exception Handling ................................................................................... 106
3.3.8 Lifetime of UNO Objects ............................................................................................. 107
acquire() and release() ........................................................................................... 107
The XComponent Interface ................................................................................... 108
Children of the XEventListener Interface ........................................................... 110
Weak Objects and References .............................................................................. 111
Differences Between the Lifetime of C++ and Java Objects ............................ 111
3.3.9 Object Identity ............................................................................................................... 113
3.4 UNO Language Bindings .......................................................................................................... 113
3.4.1 Java Language Binding ................................................................................................ 114
Getting a Service Manager ................................................................................... 114
Transparent Use of Office UNO Components ................................................... 115
Handling Interfaces ............................................................................................... 117
Type Mappings ...................................................................................................... 119
3.4.2 C++ Language Binding ................................................................................................ 131
Library Overview ................................................................................................... 131
System Abstraction Layer ..................................................................................... 133
File Access ............................................................................................................... 133
Threadsafe Reference Counting ........................................................................... 133
Threads and Thread Synchronization ................................................................. 134
Socket and Pipe ...................................................................................................... 134
Strings ...................................................................................................................... 134
Establishing Interprocess Connections ............................................................... 135
Transparent Use of Office UNO Components ................................................... 136
Type Mappings ...................................................................................................... 137
Using Weak References ......................................................................................... 145
Exception Handling in C++ .................................................................................. 146
3.4.3 OpenOffice.org Basic .................................................................................................... 147
Handling UNO Objects ......................................................................................... 147
Mapping of UNO and Basic Types ..................................................................... 153
Case Sensitivity ...................................................................................................... 161
Exception Handling ............................................................................................... 161
Listeners .................................................................................................................. 162
3.4.4 Automation Bridge ....................................................................................................... 164
Introduction ............................................................................................................ 164
Requirements .......................................................................................................... 165
A Quick Tour .......................................................................................................... 165
The Service Manager Component ....................................................................... 167
Using UNO from Automation ............................................................................. 169
Using Automation Objects From UNO .............................................................. 175
Type Mappings ...................................................................................................... 177
Automation Objects with UNO Interfaces ......................................................... 191
DCOM ..................................................................................................................... 194
The Bridge Services ............................................................................................... 196
Unsupported COM Features ................................................................................ 198
3.4.5 CLI Language Binding ................................................................................................. 199
About the Language Binding ............................................................................... 199
Terms ....................................................................................................................... 199
Requirements .......................................................................................................... 199
The Language Binding DLLs .............................................................................. 200
Type Mapping ........................................................................................................ 200
Lifetime Management and Obtaining Interfaces ............................................... 212
Writing Client Programs ....................................................................................... 213
4 Writing UNO Components 217
4.1 Required Files ............................................................................................................................. 218
4.2 Using UNOIDL to Specify New Components ....................................................................... 219
4.2.1 Writing the Specification ............................................................................................. 219
Preprocessing ......................................................................................................... 220
Grouping Definitions in Modules ....................................................................... 220
Simple Types .......................................................................................................... 221
Defining an Interface ............................................................................................. 222
Defining a Service .................................................................................................. 225
Defining a Sequence .............................................................................................. 227
Defining a Struct .................................................................................................... 228
Defining an Exception ........................................................................................... 229
Predefining Values ................................................................................................ 229
Using Comments .................................................................................................... 231
Singleton .................................................................................................................. 232
Reserved Types ...................................................................................................... 232
Published Entities .................................................................................................. 232
4.2.2 Generating Source Code from UNOIDL Definitions .............................................. 233
4.3 Component Architecture ........................................................................................................... 234
4.4 Core Interfaces to Implement ................................................................................................... 235
4.4.1 XInterface ....................................................................................................................... 237
Requirements for queryInterface() ...................................................................... 238
Reference Counting ............................................................................................... 238
4.4.2 XTypeProvider .............................................................................................................. 238
Provided Types ...................................................................................................... 239
ImplementationID .................................................................................................. 239
4.4.3 XServiceInfo ................................................................................................................... 239
Implementation Name .......................................................................................... 239
Supported Service Names .................................................................................... 240
4.4.4 XWeak ............................................................................................................................ 240
4.4.5 XComponent ................................................................................................................. 241
Disposing of an XComponent .............................................................................. 241
4.4.6 XInitialization ............................................................................................................... 241
4.4.7 XMain ............................................................................................................................ 242
4.4.8 XAggregation ............................................................................................................... 242
4.4.9 XUnoTunnel ................................................................................................................. 242
4.5 Simple Component in Java ....................................................................................................... 243
4.5.1 Class Definition with Helper Classes ......................................................................... 244
XInterface, XTypeProvider and XWeak ............................................................ 244
XServiceInfo ........................................................................................................... 244
4.5.2 Implementing your own Interfaces ............................................................................ 245
4.5.3 Providing a Single Factory Using Helper Method ................................................... 246
4.5.4 Write Registration Info Using Helper Method ......................................................... 247
4.5.5 Implementing without Helpers .................................................................................. 248
XInterface ............................................................................................................... 248
XTypeProvider ...................................................................................................... 248
XComponent .......................................................................................................... 249
4.5.6 Storing the Service Manager for Further Use ........................................................... 250
4.5.7 Create Instance with Arguments ................................................................................ 250
4.5.8 Possible Structures for Java Components ................................................................. 251
One Implementation per Component File ......................................................... 251
Multiple Implementations per Component File ................................................ 253
4.5.9 Running and Debugging Java Components ............................................................. 255
Debugging ............................................................................................................... 257
The Java Environment in OpenOffice.org .......................................................... 258
Troubleshooting ..................................................................................................... 259
4.6 C++ Component ......................................................................................................................... 261
4.6.1 Class Definition with Helper Template Classes ....................................................... 262
XInterface, XTypeProvider and XWeak ............................................................ 262
XServiceInfo ........................................................................................................... 262
4.6.2 Implementing your own Interfaces ............................................................................ 263
4.6.3 Providing a Single Factory Using a Helper Method ................................................ 263
4.6.4 Write Registration Info Using a Helper Method ...................................................... 265
4.6.5 Provide Implementation Environment ...................................................................... 265
4.6.6 Implementing without Helpers .................................................................................. 265
XInterface Implementation ................................................................................... 266
XTypeProvider Implementation .......................................................................... 267
Providing a Single Factory ................................................................................... 267
Write Registration Info .......................................................................................... 268
4.6.7 Storing the Service Manager for Further Use ........................................................... 269
4.6.8 Create Instance with Arguments ................................................................................ 269
4.6.9 Multiple Components in One Dynamic Link Library ............................................. 269
4.6.10 Building and Testing C++ Components .................................................................... 270
Build Process .......................................................................................................... 270
Test Registration and Use ..................................................................................... 270
4.7 Integrating Components into OpenOffice.org ....................................................................... 272
4.7.1 Protocol Handler ........................................................................................................... 273
Overview ................................................................................................................. 274
Implementation ...................................................................................................... 274
Configuration ......................................................................................................... 283
Installation .............................................................................................................. 284
4.7.2 Jobs .................................................................................................................................. 285
Overview ................................................................................................................. 285
Execution Environment ......................................................................................... 286
Implementation ...................................................................................................... 287
Initialization ............................................................................................................ 289
Returning Results ................................................................................................... 291
Configuration ......................................................................................................... 292
Installation .............................................................................................................. 294
Using the vnd.sun.star.jobs: URL Schema ........................................................ 294
List of supported Events ....................................................................................... 296
4.7.3 Add-Ons ........................................................................................................................ 297
Overview ................................................................................................................. 298
Guidelines ............................................................................................................... 299
Configuration ......................................................................................................... 299
Installation .............................................................................................................. 310
4.7.4 Disable Commands ...................................................................................................... 311
Configuration ......................................................................................................... 313
Disabling Commands at Runtime ....................................................................... 314
4.7.5 Intercepting Context Menus ........................................................................................ 317
Register and Remove an Interceptor ................................................................... 317
Writing an Interceptor ........................................................................................... 317
4.8 File Naming Conventions ......................................................................................................... 321
4.9 Deployment Options for Components .................................................................................... 323
4.9.1 Background: UNO Registries ...................................................................................... 323
UNO Type Library ................................................................................................. 324
Component Registration ...................................................................................... 324
4.9.2 Command Line Registry Tools ................................................................................... 325
Component Registration Tool .............................................................................. 325
UNO Type Library Tools ...................................................................................... 326
4.9.3 Manual Component Installation ................................................................................. 327
Manually Merging a Registry and Adding it to uno.ini or soffice.ini ............ 327
4.9.4 Bootstrapping a Service Manager .............................................................................. 328
4.9.5 Special Service Manager Configurations .................................................................. 329
Dynamically Modifying the Service Manager ................................................... 330
Creating a ServiceManager from a Given Registry File ................................... 331
4.10 The UNO Executable ................................................................................................................ 332
Standalone Use Case ............................................................................................. 332
Server Use Case ...................................................................................................... 334
Using the uno Executable ..................................................................................... 336
4.11 Accessing Dialogs ....................................................................................................................... 336
4.11.1 Assigning Component Methods to Control Events ................................................. 336
4.11.2 Using Dialogs in Components .................................................................................... 338
Instantiate and display a dialog ........................................................................... 338
Accept events created by dialog controls ........................................................... 340
5 Extensions 343
5.1 Extension Manager .................................................................................................................... 343
5.1.1 Deployment Items ........................................................................................................ 343
5.1.2 Installing Extensions for All or a Single User ........................................................... 343
5.1.3 Extension Manager in OpenOffice.org ...................................................................... 344
5.1.4 unopkg ........................................................................................................................... 344
5.1.5 Location of installed Extensions ................................................................................. 345
5.2 File Format .................................................................................................................................. 345
5.3 Extension Identifiers .................................................................................................................. 348
5.4 Extension Versions ..................................................................................................................... 348
5.5 description.xml ........................................................................................................................... 349
5.5.1 Description of XML Elements ..................................................................................... 349
5.5.2 Example .......................................................................................................................... 353
5.6 Simple License ............................................................................................................................ 354
5.6.1 Determining the Locale of the License ...................................................................... 355
5.7 Dependencies .............................................................................................................................. 356
5.8 System Integration ..................................................................................................................... 357
5.9 Online Update of Extensions .................................................................................................... 358
5.9.1 Running Online - Update ............................................................................................ 358
5.9.2 Concept .......................................................................................................................... 358
5.9.3 Example Scenario for Providing Updates ................................................................. 360
Using an Atom Feed .............................................................................................. 360
5.9.4 Migration of Update Information ............................................................................... 360
5.9.5 Description of the Update Information .................................................................... 361
5.9.6 Description of Atom Feed ........................................................................................... 363
5.9.7 Examples ........................................................................................................................ 363
description.xml Containing Direct Reference to the Update Information .... 363
Using the Atom Feed ............................................................................................. 364
5.10 Options Dialog ............................................................................................................................ 365
5.11 Creating the GUI of the Options Page ..................................................................................... 365
5.12 Saving and Reading Data for the Options Page .................................................................... 366
5.13 Defining the Usage of Options Pages ...................................................................................... 372
5.13.1 The Options Dialog of the Extension Manager ........................................................ 375
5.13.2 Adding a Leaf to an Existing Node ............................................................................ 375
5.13.3 Adding Several Leaves ................................................................................................ 377
5.13.4 Grouping of Leaves ...................................................................................................... 378
5.13.5 Adding Nodes .............................................................................................................. 379
5.13.6 Adding Several Nodes ................................................................................................. 380
5.13.7 Absolute Position of Leaves ........................................................................................ 380
5.13.8 Grouping of Nodes ....................................................................................................... 380
5.13.9 Assigning Nodes to Modules ...................................................................................... 381
5.13.10 Defining a Module ........................................................................................................ 382
5.13.11 Absolute Position of Nodes ......................................................................................... 383
6 Advanced UNO 385
6.1 Choosing an Implementation Language ................................................................................. 385
6.1.1 Supported Programming Environments ................................................................... 385
Java ........................................................................................................................... 386
C++ ........................................................................................................................... 386
OpenOffice.org Basic ............................................................................................. 386
OLE Automation Bridge ....................................................................................... 387
Python ...................................................................................................................... 387
6.1.2 Use Cases ....................................................................................................................... 387
Java ........................................................................................................................... 387
C++ ........................................................................................................................... 387
OpenOffice.org Basic ............................................................................................. 388
OLE Automation .................................................................................................... 388
Python ...................................................................................................................... 388
6.1.3 Recommendation .......................................................................................................... 388
6.2 Language Bindings .................................................................................................................... 388
6.2.1 Implementing UNO Language Bindings .................................................................. 389
Overview of Language Bindings and Bridges ................................................... 389
Implementation Options ....................................................................................... 390
6.2.2 UNO C++ bridges ......................................................................................................... 391
Binary UNO Interfaces .......................................................................................... 392
C++ Proxy ............................................................................................................... 393
Binary UNO Proxy ................................................................................................. 394
Additional Hints .................................................................................................... 395
6.2.3 UNO Reflection API ..................................................................................................... 396
XTypeProvider Interface ....................................................................................... 396
Converter Service ................................................................................................... 396
CoreReflection Service .......................................................................................... 396
6.2.4 XInvocation Bridge ....................................................................................................... 400
Scripting Existing UNO Objects .......................................................................... 400
Implementing UNO objects .................................................................................. 403
Example: Python Bridge PyUNO ........................................................................ 404
6.2.5 Implementation Loader ............................................................................................... 406
Shared Library Loader .......................................................................................... 408
Bridges ..................................................................................................................... 408
6.2.6 Help with New Language Bindings .......................................................................... 409
6.3 Differences Between UNO and Corba .................................................................................... 409
6.4 UNO Design Patterns and Coding Styles ............................................................................... 411