OpenOffice.org 3.1 Developer's Guide

CopyrightThis document is published under the PDL. See: http://www.openoffice.org/licenses/PDL.html

Contents

Copyright..................................................................................................2

Preface.....................................................................................45

1 First Steps.................................................................................47 Programming with UNO...............................................................................47 Fields of Application for UNO.......................................................................48 Getting Started........................................................................................... 48 Required Files ........................................................................................48 Installation Sets......................................................................................49 Configuration.......................................................................................... 50 First Contact............................................................................................ 53 How to get Objects in OpenOffice.org.........................................................59 New objects............................................................................................ 60 Document objects...................................................................................60 Objects that are provided by other objects.............................................60 Sets of objects........................................................................................61 Working with Objects..................................................................................61 Objects, Interfaces, and Services............................................................61 Using Services........................................................................................64 Example: Working with a Spreadsheet Document...................................70 Common Types.......................................................................................72 Struct...................................................................................................... 75 Any......................................................................................................... 75 Sequence................................................................................................ 78 Element Access.......................................................................................79 How do I know Which Type I Have?.............................................................843

Example: Hello Text, Hello Table, Hello Shape.............................................85 Common Mechanisms for Text, Tables and Drawings..............................85 Creating Text, Tables and Drawing Shapes..............................................91

2 Professional UNO.......................................................................97 Introduction................................................................................................. 97 API Concepts............................................................................................... 98 Data Types.................................................................................................. 99 Simple Types............................................................................................... 99 The Any Type............................................................................................. 100 Interfaces.................................................................................................. 100 Services.................................................................................................... 103 Referencing Interfaces..........................................................................105 Service Constructors.............................................................................106 Including Properties..............................................................................107 Referencing other Services...................................................................108 Service Implementations in Components..............................................109 Structs....................................................................................................... 110 Predefined Values......................................................................................111 const..................................................................................................... 111 constants.............................................................................................. 112 enum.................................................................................................... 112 Sequences................................................................................................. 113 Modules..................................................................................................... 113 Exceptions................................................................................................. 114 Singletons................................................................................................. 115 Understanding the API Reference..............................................................115 Specification, Implementation and Instances .......................................115 Object Composition ..............................................................................117 UNO Concepts........................................................................................... 117 UNO Interprocess Connections..................................................................117 Starting OpenOffice.org in Listening Mode................................................118 Importing a UNO Object............................................................................119 Characteristics of the Interprocess Bridge.................................................121 Opening a Connection...............................................................................122

Creating the Bridge...................................................................................124 Closing a Connection.................................................................................126 Example: A Connection Aware Client.........................................................127 Service Manager and Component Context................................................129 Service Manager.......................................................................................130 XMultiServiceFactory Interface .............................................................130 XContentEnumerationAccess Interface ................................................131 XSet Interface ......................................................................................132 Component Context..................................................................................132 ComponentContext API ........................................................................133 Availability............................................................................................ 135 Compatibility Issues and Migration Path...............................................136 Using UNO Interfaces................................................................................137 Properties.................................................................................................. 140 Collections and Containers........................................................................146 Event Model.............................................................................................. 148 Exception Handling...................................................................................150 User-Defined Exceptions ......................................................................150 Runtime Exceptions .............................................................................151 Good Exception Handling .....................................................................152 Lifetime of UNO objects.............................................................................154 acquire() and release()..............................................................................154 The XComponent Interface........................................................................155 Children of the XEventListener Interface...................................................158 Weak Objects and References...................................................................158 Differences Between the Lifetime of C++ and Java Objects......................159 Object Identity........................................................................................... 161 UNO Language Bindings............................................................................162 Java Language Binding..............................................................................162 Getting a Service Manager........................................................................163 Transparent Use of Office UNO Components.............................................165 The bootstrap method..........................................................................165 SDK tooling .......................................................................................... 166 Finding a UNO Installation ....................................................................167 Handling Interfaces...................................................................................168 Type Mappings.......................................................................................... 170 Mapping of Simple Types .....................................................................170 Mapping of String .................................................................................171 Mapping of Type ...................................................................................171 Mapping of Any ....................................................................................171 Mapping of Sequence Types......................................................................173

Mapping of Enum Types............................................................................174 Mapping of Struct Types............................................................................175 Mapping of Exception Types......................................................................179 Mapping of Interface Types.......................................................................180 Mapping of UNOIDL...................................................................................182 Mapping of UNOIDL Typedefs ...............................................................182 Mapping of Individual UNOIDL Constants .............................................182 Mapping of UNOIDL Constant Groups ...................................................183 Mapping of UNOIDL Modules ................................................................183 Mapping of Services..................................................................................183 Mapping of Singletons...............................................................................185 Inexact approximation of UNO Value Semantics........................................185 C++ Language Binding.............................................................................186 Library Overview ..................................................................................186 System Abstraction Layer ....................................................................188 File Access ........................................................................................... 188 Threadsafe Reference Counting ...........................................................189 Threads and Thread Synchronization ...................................................189 Socket and Pipe ...................................................................................189 Strings ................................................................................................. 190 Establishing Interprocess Connections......................................................190 Transparent Use of Office UNO Components.............................................192 The bootstrap function .........................................................................192 SDK tooling .......................................................................................... 192 Finding a UNO Installation ....................................................................193 Type Mappings.......................................................................................... 194 Mapping of Simple Types .....................................................................194 Mapping of Type ...................................................................................196 Mapping of Any ....................................................................................196 Mapping of Struct Types............................................................................197 Mapping of Interface Types.......................................................................199 Mapping of Sequence Types......................................................................200 Mapping of Sequence Types .................................................................202 Mapping of Services..................................................................................203 Mapping of Singletons...............................................................................205 Using Weak References.............................................................................205

Exception Handling in C++.......................................................................206 OpenOffice.org Basic.................................................................................208 Handling UNO Objects...............................................................................208 Accessing UNO Services ......................................................................208 Instantiating UNO Services........................................................................210 Getting Information about UNO Objects....................................................211 Checking for interfaces during runtime ................................................211 Testing if an object is a struct during runtime ......................................212 Testing objects for identity during runtime ..........................................213 Inspecting interfaces during debugging ...............................................213 Inspecting properties during debugging ..............................................214 Inspecting Methods During Debugging ................................................215 Mapping of UNO and Basic Types..............................................................216 Mapping of Simple Types...........................................................................216 Mapping of Sequences and Arrays............................................................219 Mapping of Structs....................................................................................222 Mapping of Enums and Constant Groups...................................................224 Case Sensitivity......................................................................................... 225 Exception Handling...................................................................................225 Listeners................................................................................................... 227 Automation Bridge....................................................................................229 Requirements .......................................................................................230 A Quick Tour ......................................................................................... 231 The Service Manager Component.............................................................233 Instantiation ......................................................................................... 233 Visual Basic: ......................................................................................... 233 VBScript with WSH: ..............................................................................234 JScript with WSH: .................................................................................234 Registry Entries ....................................................................................234 From UNO Objects to Automation Objects ............................................235 Using UNO from Automation.....................................................................236 Calling Functions and Accessing Properties...............................................236 Return Values............................................................................................ 238 Usage of Types.......................................................................................... 240 Interfaces ............................................................................................. 240 Structs ................................................................................................. 240 Using Automation Objects from UNO.........................................................242 Instantiation ......................................................................................... 243 Properties with Arguments ...................................................................244 Optional Parameters, Default Values, Variable Argument Lists ............245 Named Arguments ...............................................................................245

Type Mappings.......................................................................................... 246 Default Mappings......................................................................................247 Mapping of Simple Types...........................................................................248 Mapping of Hyper and Decimal.................................................................249 Mapping of String......................................................................................250 Mapping of Interfaces and Structures........................................................250 Mapping of Sequence................................................................................252 Mapping of Type........................................................................................254 Conversion Mappings................................................................................255 Client-Side Conversions.............................................................................256 Client-Side Conversions .......................................................................257 Client-Side Conversions .......................................................................258 Value Objects............................................................................................ 258 Exceptions and Errorcodes........................................................................260 Automation Objects with UNO Interfaces..................................................263 Requirements .......................................................................................264 Examples ............................................................................................. 265 DCOM........................................................................................................ 266 The Bridge Services...................................................................................270 Service: com.sun.star.bridge.oleautomation.BridgeSupplier ................270 Service: com.sun.star.bridge.OleBridgeSupplierVar1 ...........................272 Service: com.sun.star.bridge.oleautomation.ApplicationRegistration ...272 Service: com.sun.star.bridge.oleautomation.Factory ............................272 Unsupported COM Features.......................................................................273 CLI Language Binding................................................................................273 Terms ................................................................................................... 273 Requirements .......................................................................................274 Running on 64 Bit Platforms..................................................................275 Changes in OpenOffice.org 3.0.............................................................275 Language Binding DLLs.............................................................................276 Modules ............................................................................................... 277 Type Mapping............................................................................................ 277 Type Name Decoration..............................................................................278 Type Mappings.......................................................................................... 278 Simple Types ........................................................................................278 any ....................................................................................................... 279

interface .............................................................................................. 281 Methods ............................................................................................... 281 Parameter Types (in,out,in/out) ............................................................281 Exceptions ........................................................................................... 283 One-Way Methods ................................................................................284 Attributes ............................................................................................. 284 XInterface ............................................................................................ 284 struct ................................................................................................... 285 Polymorphic structs .............................................................................286 const .................................................................................................... 286 constants ............................................................................................. 286 enum ................................................................................................... 287 sequence ............................................................................................. 287 exception ............................................................................................. 287 services ............................................................................................... 288 singletons ............................................................................................ 289 Additional Structures.................................................................................289 ExceptionAttribute Attribute ................................................................289 OnewayAttribute ..................................................................................289 BoundPropertyAttribute .......................................................................290 TypeParametersAttribute .....................................................................290 ParameterizedTypeAttribute .................................................................290 TypeArgumentsAttribute ......................................................................290 PolymorphicType ..................................................................................291 Lifetime Management and Obtaining Interfaces........................................291 Writing Client Programs.............................................................................292 The Override Problem................................................................................295 Important Interfaces and Implementations...............................................297 uno.util.WeakBase ...............................................................................297 uno.util.WeakComponentBase .............................................................298

3 Writing UNO Components.........................................................299 Required Files............................................................................................ 300 OpenOffice.org Software Development Kit (SDK) .................................300 GNU Make ............................................................................................ 301 Using UNOIDL to Specify New Components...............................................302 Writing the Specification...........................................................................302 Preprocessing............................................................................................ 303 Grouping Definitions in Modules................................................................304 Simple Types............................................................................................. 305

Defining an Interface.................................................................................306 Attributes ............................................................................................. 306 Methods ............................................................................................... 309 Defining a Service.....................................................................................310 Old-style Services ................................................................................311 Defining a Sequence.................................................................................314 Defining a Struct.......................................................................................314 Defining an Exception...............................................................................316 Predefining Values.....................................................................................317 Const and Constants ............................................................................317 Enum ................................................................................................... 318 Using Comments.......................................................................................319 Singleton................................................................................................... 320 Reserved Types......................................................................................... 321 Array .................................................................................................... 321 Union ................................................................................................... 321 Published Entities......................................................................................321 Component Architecture...........................................................................322 Core Interfaces to Implement....................................................................323 XInterface.................................................................................................. 326 Requirements for queryInterface() .......................................................327 Reference Counting .............................................................................328 XTypeProvider............................................................................................ 328 Provided Types .....................................................................................328 ImplementationID ................................................................................329 XServiceInfo.............................................................................................. 329 Implementation Name .........................................................................329 Supported Service Names ....................................................................330 XWeak....................................................................................................... 331 XComponent.............................................................................................. 331 Disposing of an XComponent ...............................................................332 XInitialization............................................................................................ 332 XMain........................................................................................................ 333 XAggregation............................................................................................ 333 XUnoTunnel............................................................................................... 334 Simple Component in Java........................................................................335

Class Definition with Helper Class.............................................................336 XInterface, XTypeProvider and XWeak .................................................336 XServiceInfo ......................................................................................... 337 Implementing Your Own Interfaces............................................................337 Providing a Single Factory Using a Helper Method.....................................339 Write Registration Info Using a Helper Method..........................................340 Implementing without Helpers..................................................................342 XInterface ............................................................................................ 342 XTypeProvider ......................................................................................343 XComponent ........................................................................................343 Storing the Service Manager for Further Use.............................................345 Create Instance with Arguments...............................................................345 Possible Structures for Java Components..................................................346 One Implementation per Component File .............................................347 Implementation Class with Component Operations and Inner Implementation Class ..........................................................................348 Multiple Implementations per Component File .....................................349 Additional UNO Types ...........................................................................353 Running and Debugging Java Components................................................354 Register Component File...........................................................................354 Make Registration Available to OpenOffice.org..........................................355 Test the Registration..................................................................................355 Debugging................................................................................................. 356 Support for GNU make .........................................................................356 Component Debugging ........................................................................357 The Java Environment in OpenOffice.org...................................................358 Troubleshooting......................................................................................... 359 Check Registry Keys .............................................................................359 Check the Java VM settings ..................................................................361 Check the Manifest ..............................................................................361 Adjust CLASSPATH for Additional Classes .............................................361 Disable Debug Options ........................................................................362 C++ Component.......................................................................................362 Class Definition with Helper Template Classes..........................................363 XInterface, XTypeProvider and XWeak .................................................363 XServiceInfo ......................................................................................... 364 Implementing your own Interfaces............................................................365 Providing a Single Factory Using a Helper Method.....................................365 Write Registration Info Using a Helper Method..........................................368 Provide Implementation Environment.......................................................368 Implementing without Helpers..................................................................369

XInterface Implementation ..................................................................369 XTypeProvider Implementation ............................................................371 Providing a Single Factory ....................................................................372 Write Registration Info .........................................................................373 Storing the Service Manager for Further Use.............................................374 Create Instance with Arguments...............................................................374 Multiple Components in One Dynamic Link Library...................................375 Building and Testing C++ Components.....................................................375 Build Process ........................................................................................ 375 Test Registration and Use .....................................................................376 Integrating Components into OpenOffice.org............................................377 Protocol Handler........................................................................................379 Overview .............................................................................................. 379 Implementation......................................................................................... 380 Java Protocol Handler - vnd.sun.star.framework.ExampleHandler ........383 C++ Protocol Handler - org.openoffice.Office.addon.example .............385 Configuration............................................................................................ 393 Configuration for vnd.sun.star.framework.ExampleHandler .................394 Configuration for org.openoffice.Office.addon.example .......................395 Installation................................................................................................ 396 Jobs........................................................................................................... 396 Execution Environment.............................................................................398 Implementation......................................................................................... 399 Initialization............................................................................................... 401 Returning Results......................................................................................404 Configuration............................................................................................ 405 Installation................................................................................................ 408 Using the vnd.sun.star.jobs: URL Schema.................................................409 List of Supported Events...........................................................................412 Add-Ons.................................................................................................... 413 Overview .............................................................................................. 413 Guidelines................................................................................................. 414 Add-Ons Submenu ...............................................................................414 Custom Top-Level Menu .......................................................................415 Toolbar ................................................................................................. 415 Add-On Help menu ...............................................................................415

Configuration............................................................................................ 415 Menus....................................................................................................... 416 Submenu in Tools - Add-Ons.................................................................417 Top-level Menu .....................................................................................420 Toolbars..................................................................................................... 422 Images for Toolbars and Menus.................................................................425 Help Integration........................................................................................428 Installation................................................................................................ 431 Disable Commands...................................................................................431 Configuration .......................................................................................433 Disabling Commands at Runtime .........................................................435 Intercepting Context Menus......................................................................440 Register and Remove an Interceptor ....................................................441 Writing an Interceptor ..........................................................................441 Querying a Menu Structure ..................................................................442 Changing a Menu .................................................................................443 Finishing Interception ...........................................................................444 File Naming Conventions...........................................................................447 Deployment Options for Components.......................................................449 Background: UNO Registries ................................................................449 Component Registration ......................................................................451 Command Line Registry Tools....................................................................451 Component Registration Tool ...............................................................452 UNO Type Library Tools ........................................................................453 Manual Component Installation.................................................................454 Manually Merging a Registry and Adding it to uno.ini or soffice.ini ......454 Bootstrapping a Service Manager.............................................................455 Special Service Manager Configurations...................................................458 Dynamically Modifying the Service Manager .......................................458 Creating a ServiceManager from a Given Registry File .........................460 The UNO Executable..................................................................................461 Standalone Use Case.................................................................................462 Server Use Case........................................................................................465 Using the UNO Executable........................................................................467 Accessing Dialogs......................................................................................467 Assigning Component Methods to Control Events.....................................468 Using Dialogs in Components....................................................................469 Instantiate and display a dialog ...........................................................470 Accept events created by dialog controls ............................................472

4 Extensions...............................................................................477 Extension Manager....................................................................................477 Deployment Items.....................................................................................478 Installing Extensions for All or a Single User..............................................478 Extension Manager in OpenOffice.org.......................................................479 unopkg...................................................................................................... 479 Location of Installed Extensions................................................................480 Extension Layers.......................................................................................481 Unprocessed Content............................................................................482 The Future of Layers ............................................................................482 Checklist for Writing Extensions................................................................483 File Format................................................................................................ 484 Runtime Libraries .................................................................................485 Shared Library UNO Components ........................................................485 Shared Library UNO Components for particular Platforms ...................485 RDB Type Library..................................................................................486 Jar Type Library.....................................................................................486 Uno Jar Components.............................................................................486 UNO Python Components......................................................................487 OpenOffice.org Basic Libraries..............................................................487 Dialog Libraries.....................................................................................487 Configuration Data Files........................................................................487 Configuration Schema Files...................................................................488 Extension Tooltip Description................................................................488 Executable Files ...................................................................................488 description.xml.......................................................................................... 489 Description of XML Elements.....................................................................490 Element /description.............................................................................490 Element /description/identifier..............................................................491 Element /description/version................................................................491 Element /description/platform...............................................................491 Element /description/registration..........................................................492 Element /description/registration/simple-license..................................492 Element /description/registration/simple-license/license-text...............494 Element /description/dependencies......................................................494 Element /description/dependencies/OpenOffice.org-minimal-version. . .495

Element /description/dependencies/OpenOffice.org-maximal-version. .495 Element /description/update-information..............................................496 Element /description/update-information/src........................................496 Element /description/publisher.............................................................497 Element /description/publisher/name...................................................497 Element /description/release-notes.......................................................498 Element /description/release-notes/src.................................................498 Element /description/display-name.......................................................499 Element /description/display-name/name.............................................499 Element /description/icon.....................................................................499 Element /description/icon/default.........................................................500 Element /description/icon/high-contrast...............................................500 Element /description/extension-description..........................................500 Element /description/extension-description/src....................................501 Localized XML Elements............................................................................501 Example.................................................................................................... 505 Display Name............................................................................................ 507 Icon........................................................................................................... 507 Extension Description................................................................................507 Extension Identifiers..................................................................................508 Extension Versions....................................................................................509 Target Platform.......................................................................................... 510 Platform Tokens.....................................................................................510 Backward Compatibility of Platforms....................................................511 Generating the Platform String in the Build Environment.....................512 Simple License.......................................................................................... 512 Important Issues...................................................................................514 Dependencies........................................................................................... 514 Publisher Information................................................................................516 System Integration....................................................................................516 Online Update of Extensions.....................................................................516 Running Online - Update...........................................................................517 Concept..................................................................................................... 518 Example Scenario for Providing Updates...................................................519 Using an Atom Feed .............................................................................519 Migration of Update Information................................................................520 Description of the Update Information......................................................520 Element /description.............................................................................520 Element /description/identifier..............................................................521 Element /description/version................................................................521 Element /description/update-download.................................................522

Element /description/update-download/src...........................................522 Element /description/update-website....................................................522 Element /description/update-website/src..............................................523 Element /description/dependencies......................................................523 Element /description/dependencies/OpenOffice.org-minimal-version. . .524 Element /description/dependencies/OpenOffice.org-maximal-version. .524 Element /description/publisher.............................................................525 Element /description/publisher/name...................................................525 Element /description/release-notes.......................................................526 Element /description/release-notes/src.................................................526 Description of Atom Feed..........................................................................527 Examples.................................................................................................. 527 description.xml Containing Direct Reference to the Update Information ............................................................................................................. 527 Using the Atom Feed ............................................................................528 Options Dialog........................................................................................... 529 Available samples ................................................................................530 Creating the GUI of the Options Page........................................................530 Saving and Reading Data for the Options Page.........................................531 Defining the Usage of Options Pages........................................................541 The Options Dialog of the Extension Manager...........................................546 Adding a Leaf to an Existing Node.............................................................546 Adding Several Leaves..............................................................................548 Grouping of Leaves...................................................................................550 Adding Nodes............................................................................................ 551 Adding Several Nodes...............................................................................553 Absolute Position of Leaves.......................................................................553 Grouping of Nodes.....................................................................................554 Assigning Nodes to Modules......................................................................556 Defining a Module.....................................................................................557 Absolute Position of Nodes........................................................................557 Help Content............................................................................................. 559 Extension help format ..........................................................................559 Deployment.......................................................................................... 561 Error handling ......................................................................................562 Integration into the OpenOffice.org help system .................................562

Help Viewer Contents page ..................................................................562 Help Viewer Index page .......................................................................563 Help Viewer Find page .........................................................................563 Help Viewer Bookmarks page ..............................................................564 Context sensitive help and extended tool tips .....................................564 Links .................................................................................................... 564 Images ................................................................................................. 565 File Format ........................................................................................... 565

5 Advanced UNO.........................................................................567 Choosing an Implementation Language ...............................................567 C++ ..................................................................................................... 569 OpenOffice.org Basic ...........................................................................569 OLE Automation Bridge ........................................................................570 Python ................................................................................................. 570 Use Cases ............................................................................................ 570 C++ ..................................................................................................... 571 OpenOffice.org Basic ...........................................................................571 OLE Automation ...................................................................................571 Python ................................................................................................. 571 Recommendation .................................................................................571 Language Bindings....................................................................................572 Implementing UNO Language Bindings.....................................................572 Overview of Language Bindings and Bridges .......................................573 Code Generator ...................................................................................573 UNO Bridge .......................................................................................... 573 UNO Component Loader ......................................................................574 Bootstrapping ......................................................................................574 Implementation Options ......................................................................575 UNO C++ Bridges.....................................................................................576 Binary UNO Interfaces ..........................................................................577 C++ Proxy ........................................................................................... 578 Binary UNO Proxy .................................................................................580 Additional Hints ....................................................................................582 UNO Reflection API....................................................................................582 XTypeProvider Interface .......................................................................583 Converter Service ................................................................................583 CoreReflection Service .........................................................................583 Invocation ............................................................................................ 585 InvocationAdapterFactory ....................................................................586

XTypeDescription .................................................................................587 XInvocation Bridge....................................................................................588 Scripting Existing UNO Objects ............................................................588 Argument Conversion ..........................................................................590 Exception Handling ..............................................................................591 Property Support ..................................................................................591 Implementing UNO objects ..................................................................592 Example Python Bridge PyUNO.................................................................593 Implementation Loader.............................................................................596 Shared Library Loader ..........................................................................598 Bridges ................................................................................................ 599 Help with New Language Bindings............................................................600 Differences Between UNO and Corba........................................................600 UNO Design Patterns and Coding Styles....................................................602 Double-Checked Locking ......................................................................603

6 Office Development.................................................................607 OpenOffice.org Application Environment...................................................607 Desktop Environment................................................................................608 Framework API.......................................................................................... 609 Frame-Controller-Model Paradigm in OpenOffice.org.................................610 Frames...................................................................................................... 611 Linking Components and Windows ......................................................611 Communication through Dispatch Framework .....................................613 Components in Frames ........................................................................613 Controllers................................................................................................. 614 Windows.................................................................................................... 615 Dispatch Framework..................................................................................615 Using the Desktop.....................................................................................616 Using the Component Framework.............................................................622 Getting Frames, Controllers and Models from Each Other.........................623 Frames...................................................................................................... 624 XFrame ................................................................................................ 624 Frame Hierarchies ................................................................................624 Frame Actions ......................................................................................627

XFramesSupplier ..................................................................................629 XDispatchProvider and XDispatchProviderInterception ........................629 XStatusIndicatorFactory .......................................................................630 Controllers................................................................................................. 630 XController ........................................................................................... 630 XDispatchProvider ................................................................................631 XSelectionSupplier ...............................................................................631 XContextMenuInterception ...................................................................631 Document Specific Controller Services ................................................632 Models....................................................................................................... 633 XModel ................................................................................................. 634 XModifiable .......................................................................................... 635 XStorable ............................................................................................. 635 XPrintable ............................................................................................ 635 XEventBroadcaster ..............................................................................635 XEventsSupplier ...................................................................................636 XDocumentInfoSupplier .......................................................................636 XViewDataSupplier ..............................................................................636 Document Specific Features ................................................................637 Window Interfaces.....................................................................................638 XWindow .............................................................................................. 638 XTopWindow ......................................................................................... 639 XWindowPeer .......................................................................................639 Creating Frames Manually.........................................................................640 Frame Creation ....................................................................................640 Assigning Windows to Frames ..............................................................640 Setting Components into Frame Hierarchies ........................................641 Handling Documents.................................................................................643 Loading Documents .............................................................................643 URL Parameter .....................................................................................651 Target Frame ........................................................................................651 Closing Documents...................................................................................655 Reacting Upon Closing .........................................................................655 How to Trigger Closing .........................................................................656 XCloseable ........................................................................................... 657 Storing Documents....................................................................................661 Printing Documents .............................................................................663 Using the Dispatch Framework..................................................................663 Command URL.......................................................................................... 664 Processing Chain.......................................................................................664 Dispatch Process.......................................................................................666

Getting a Dispatch Object ....................................................................667 Listening for Status Information ...........................................................668 Listening for Context Changes .............................................................669 Dispatching a Command ......................................................................670 Dispatch Results........................................................................................ 671 Dispatch Interception................................................................................672 Java Window Integration............................................................................674 The Window Handle .............................................................................674 Using the Window Handle ....................................................................675 Legal Solution ......................................................................................676 More Remote Problems ........................................................................678 Common Application Features...................................................................679 Clipboard ............................................................................................. 679 Copying Data .......................................................................................681 Becoming a Clipboard Viewer ..............................................................684 OpenOffice.org Clipboard Data Formats ...............................................685 Internationalization...................................................................................686 Introduction ......................................................................................... 686 Overview and Using the API......................................................................687 XLocaleData ......................................................................................... 687 XCharacterClassification ......................................................................687 XCalendar ............................................................................................ 687 XExtendedCalendar .............................................................................688 XNumberFormatCode ...........................................................................688 XNativeNumberSupplier .......................................................................688 XCollator .............................................................................................. 689 XTransliteration ....................................................................................689 XTextConversion ..................................................................................690 XBreakIterator .....................................................................................690 XIndexEntrySupplier ............................................................................690 XExtendedIndexEntrySupplier .............................................................691 Implementing a New Locale......................................................................691 XLocaleData ......................................................................................... 691 XCalendar ............................................................................................ 695 XCharacterClassification ......................................................................696 XBreakIterator .....................................................................................696

XCollator .............................................................................................. 698 XTransliteration ....................................................................................699 XTextConversion ..................................................................................700 XNativeNumberSupplier .......................................................................704 XIndexEntrySupplier ............................................................................705 A Comment on Search and Replace .....................................................706 Linguistics................................................................................................. 706 Services Overview ...............................................................................707 Using Spellchecker....................................................................................710 Relevant properties ..............................................................................711 Using Hyphenator......................................................................................712 Relevant properties ..............................................................................713 Using Thesaurus........................................................................................ 715 Events....................................................................................................... 716 Implementing a Spell Checker...................................................................717 Implementing a Hyphenator......................................................................719 Implementing a Thesaurus........................................................................720 Integrating Import and Export Filters.........................................................721 Introduction.......................................................................................... 721 Approaches........................................................................................... 722 Checklist for filter developers...............................................................723 Filtering Process........................................................................................724 Loading content....................................................................................724 Storing content.....................................................................................726 Filter.......................................................................................................... 727 Configuring a Filter in OpenOffice.org.......................................................730 Structure of the configuration...............................................................730 TypeDetection ......................................................................................731 Properties of a Type...................................................................................732 Properties of a Filter..................................................................................734 Sample configuration for an API based filter.........................................737 Sample configuration for an XML based filter.......................................738 Sample configuration for an xslt based filter........................................739 Filter Options............................................................................................. 740 Properties of a FrameLoader......................................................................741 Document API Filter Development.............................................................742 XML Based Filter Development..................................................................742 Introduction ......................................................................................... 742 Sample implementations......................................................................743 Writing the Filtering Component................................................................743 XImportFilter ........................................................................................743

XExportFilter ........................................................................................744 XDocumentHandler ..............................................................................744 The Importer............................................................................................. 745 Evaluating XImportFilter Parameters ....................................................745 Importer Filtering .................................................................................746 Parsing the Result ................................................................................746 The Exporter............................................................................................. 747 Evaluating XExportFilter Parameters ....................................................747 Exporter Filtering .................................................................................748 XML Filter Detection..................................................................................748 Requirements for Deep Detection ........................................................749 Extending the File Type Definition ........................................................749 The ExtendedTypeDetection Service Implementation ..........................750 TypeDetection.xcu DetectServices Entry ..............................................751 Number Formats.......................................................................................752 Managing Number Formats.......................................................................752 NumberFormats Service .......................................................................753 XNumberFormatTypes ..........................................................................754 Applying Number Formats.........................................................................754 NumberFormatter Service ....................................................................754 XNumberformatPreviewer ....................................................................755 Document Events......................................................................................757 Path Organization......................................................................................764 Path Settings............................................................................................. 764 Configuration .......................................................................................766 Accessing Path Settings .......................................................................769 Path Variables............................................................................................ 774 Predefined Variables..................................................................................775 Custom Path Variables...............................................................................778 Syntax ................................................................................................. 778 Environment Values .............................................................................778 Rules .................................................................................................... 779 Analyzing User-Defined Rules ..............................................................779 Configuration .......................................................................................780 Resolving Path Variables...........................................................................783 OpenOffice.org Single Sign-On API............................................................786

Overview .............................................................................................. 786 Implementing the OpenOffice.org SSO API ..........................................787 XSSOManager ......................................................................................788 XSSOInitiatorContext ...........................................................................788 XSSOAcceptorContext ..........................................................................789

7 Text Documents.......................................................................793 Example: Fields in a Template...................................................................795 Example: Visible Cursor Position...............................................................798 Handling Text Document Files...................................................................800 Creating and Loading Text Documents .................................................800 Saving Text Documents.............................................................................802 Storing ................................................................................................. 802 Exporting ............................................................................................. 803 Printing Text Documents............................................................................804 Printer and Print Job Settings ...............................................................804 Printing Multiple Pages on one Page ....................................................806 Working with Text Documents...................................................................807 Word Processing ...................................................................................807 Editing Text............................................................................................... 807 Strings ................................................................................................. 807 Text Contents Other Than Strings ........................................................810 Control Characters ...............................................................................811 Iterating over Text.....................................................................................812 Inserting a Paragraph where no Cursor can go..........................................815 Sorting Text............................................................................................... 815 Inserting Text Files.....................................................................................816 Auto Text................................................................................................... 816 Formatting................................................................................................. 817 Navigating................................................................................................. 827 Cursors ................................................................................................ 827 Locating Text Contents .........................................................................828 Search and Replace .............................................................................829 Tables........................................................................................................ 832 Table Architecture ................................................................................832 Named Table Cells in Rows, Columns and the Table Cursor.......................835 Indexed Cells and Cell Ranges...................................................................839 Table Naming, Sorting, Charting and Autoformatting................................839 Text Table Properties.................................................................................840 Inserting Tables......................................................................................... 842

Accessing Existing Tables..........................................................................846 Text Fields.................................................................................................. 847 Bookmarks................................................................................................ 854 Indexes and Index Marks...........................................................................855 Indexes ................................................................................................ 855 Index marks ......................................................................................... 858 Reference Marks........................................................................................ 859 Footnotes and Endnotes............................................................................861 Shape Objects in Text................................................................................864 Base Frames vs. Drawing Shapes ........................................................864 Drawing Shapes ...................................................................................868 Text Frames............................................................................................... 868 Embedded Objects....................................................................................870 Graphic Objects......................................................................................... 873 Drawing Shapes........................................................................................874 Redline...................................................................................................... 878 Ruby.......................................................................................................... 878 Overall Document Features.......................................................................879 Styles ................................................................................................... 879 Paragraph Styles ..................................................................................882 Frame Styles ........................................................................................882 Page Styles .......................................................................................... 883 Numbering Styles ................................................................................883 Settings..................................................................................................... 885 General Document Information ............................................................885 Document Properties ...........................................................................885 Creating Default Settings .....................................................................886 Creating Document Settings ................................................................886 Line Numbering and Outline Numbering...................................................887 Paragraph and Outline Numbering .......................................................887 Line Numbering ...................................................................................890 Number Formats ..................................................................................890 Text Sections............................................................................................. 891 Page Layout.............................................................................................. 892 Columns.................................................................................................... 893 Link Targets............................................................................................... 895

Text Document Controller..........................................................................896 TextView.................................................................................................... 896 TextViewCursor.......................................................................................... 899

8 Spreadsheet Documents...........................................................901 Example: Adding a New Spreadsheet........................................................903 Example: Editing Spreadsheet Cells..........................................................904 Handling Spreadsheet Documents Files....................................................905 Creating and Loading Spreadsheet Documents ...................................905 Saving Spreadsheet Documents................................................................906 Storing ................................................................................................. 906 Exporting ............................................................................................. 907 Filter Options............................................................................................. 908 Filter Options for Lotus, dBase and DIF Filters ......................................910 Filter Options for the CSV Filter ............................................................910 Printing Spreadsheet Documents..............................................................912 Printer and Print Job Settings ...............................................................912 Page Breaks and Scaling for Printout ...................................................914 Print Areas ........................................................................................... 914 Working With Spreadsheet Documents.....................................................915 Document Structure .............................................................................915 Spreadsheet Services - Overview..............................................................919 Capabilities of Spreadsheet.......................................................................919 Capabilities of SheetCellRange..................................................................921 Capabilities of SheetCell............................................................................923 Capabilities of SheetCellRanges Container................................................925 Capabilities of Columns and Rows.............................................................927 Spreadsheet.............................................................................................. 929 Properties of Spreadsheet ....................................................................929 Naming ................................................................................................ 929 Inserting Cells, Moving and Copying Cell Ranges .................................929 Page Breaks ......................................................................................... 930 Cell Ranges............................................................................................... 931 Properties of Cell Ranges...........................................................................931 Cell and Cell Range Access........................................................................931 Merging Cell Ranges into a Single Cell......................................................933 Column and Row Access............................................................................933 Data Array................................................................................................. 934 Absolute Address.......................................................................................934 Fill Series................................................................................................... 935

Operations................................................................................................ 936 Multiple Operations...................................................................................937 Handling Array Formulas...........................................................................938 Cells.......................................................................................................... 939 Properties of SheetCell..............................................................................939 Access to Formulas, Values and Errors......................................................940 Access to Text Content..............................................................................941 Absolute Address.......................................................................................942 Cell Annotations........................................................................................943 Cell Ranges and Cells Container................................................................944 Properties of SheetCellRanges .............................................................945 Access to Single Cell Ranges in SheetCellRanges Container ................945 Columns and Rows....................................................................................947 Formatting................................................................................................. 949 Cell Formatting ....................................................................................949 Character and Paragraph Format..............................................................950 Indentation................................................................................................ 951 Equally Formatted Cell Ranges..................................................................951 Cell Format Ranges ..............................................................................951 Unique Cell Format Ranges ..................................................................952 Table Auto Formats....................................................................................954 Conditional Formats..................................................................................957 Navigating................................................................................................. 959 Cell Cursor................................................................................................. 959 Cursor Movement ................................................................................960 Used Area ............................................................................................ 962 Referencing Ranges by Name...................................................................962 Named Ranges.......................................................................................... 963 Label Ranges............................................................................................. 965 Querying for Cells with Specific Properties................................................966 Search and Replace...................................................................................968 Sorting....................................................................................................