Documentation/DevGuide/Writing UNO Components

LibreOffice can be extended by UNO components. UNO components are shared libraries or jar files with the ability to instantiate objects that can integrate themselves into the UNO environment. A UNO component can access existing features of LibreOffice, and it can be used from within LibreOffice through the object communication mechanisms provided by UNO.

LibreOffice provides many entry points for these extensions.


 * Arbitrary objects written in Java or C++ can be called from the user interface, display their own GUI, and work with the entire application.
 * Calc Add-Ins can be used to create new formula sets that are presented in the formula autopilot.
 * Chart Add-Ins can insert new Chart types into the charting tool.
 * New database drivers can be installed into the office to extend data access.
 * Entire application modules are exchangeable, for instance the linguistics module.
 * It is possible to create new document types and add them to the office. For instance, a personal information manager could add message, calendar, task and journal document components, or a project manager could support a new project document.
 * Developers can leverage the LibreOffice XML file format to read and write new file formats through components.

From OpenOffice.org 1.1.0 there is comprehensive support for component extensions. The entire product cycle of a component is now covered:


 * The design and development of components has been made easier by adding wizards for components to the NetBeans IDE. You can find more detailed info under https://wiki.openoffice.org/wiki/OpenOffice_NetBeans_Integration.
 * Components can integrate themselves into the user interface, using simple configuration files. You can add new menus, toolbar items, and help items for a component simply by editing XML configuration files.
 * Components are deployed with the Extension Manager. See chapter Extensions.
 * Last but not least, this is not the only way to add features to the office. Learning how to write components and how to use the LibreOffice API at the same time teaches you the techniques used in the LibreOffice code base, thus enabling you to work with the existing LibreOffice source code, extend it or introduce bug fixes.

Components are the basis for all of these extensions. This chapter teaches you how to write UNO components. It assumes that you have at least read the chapter First Steps and—depending on your target language—the section about the Java or C++ language binding in Professional UNO.

LibreOffice Software Development Kit (SDK)
The SDK provides a build environment for your projects, separate from the LibreOffice build environment. It contains the necessary tools for UNO development, C and C++ libraries, JARs, UNO type definitions and example code. But most of the necessary libraries and files are shared with an existing LibreOffice installation which is a prerequisite for a SDK.

The SDK development tools (executables) contained in the SDK are used in the following chapter. Become familiar with the following table that lists the executables from the SDK. These executables are found in the platform specific bin folder of the SDK installation. In Windows, they are in the folder &lt;SDK&gt;\bin, on Linux they are stored in &lt;SDK&gt;/linux/bin and on Solaris in &lt;SDK&gt;/solaris/bin.

GNU Make
The makefiles in the SDK assume that the GNU make is used. Documentation for GNU make command line options and syntax are available at www.gnu.org. In Windows, not every GNU make seems stable, notably some versions of Cygwin make were reported to have problems with the SDK makefiles. Other GNU make binaries, such as the one from unxutils.sourceforge.net work well even on the Windows command line. The package UnxUtils comes with a zsh shell and numerous utilities, such as find, sed. To install UnxUtils, download and unpack the archive (if the links on unxutils.sourceforge.net are still broken, try with sourceforge.net/projects/unxutils), and add \usr\local\wbin to the PATH environment variable. Now launch sh.exe from \bin and issue the command make from within zsh or use the Windows command line to run make. For further information about zsh, go to zsh.sunsite.dk.

Using UNOIDL to Specify New Components
Component development does not necessarily start with the declaration of new interfaces or new types. Try to use the interfaces and types already defined in the LibreOffice API. If existing interfaces cover your requirements and you need to know how to implement them in your own component, go to section Component Architecture. The following describes how to declare your own interfaces and other types you might need.

UNO uses its own meta language UNOIDL (UNO Interface Definition Language) to specify types. Using a meta language for this purpose enables you to generate language specific code, such as header files and class definitions, to implement objects in any target language supported by UNO. UNOIDL keeps the foundations of UNO language independent and takes the burden of mechanic language adaptation from the developer's shoulders when implementing UNO objects.

To define a new interface, service or other entity, write its specification in UNOIDL, then compile it with the UNOIDL compiler idlc. After compilation, merge the resulting binary type description into a type library that is used during the make process to create necessary language dependent type representations, such as header or Java class files. The chapter Professional UNO provides the various type mappings used by  and   in the language binding sections. Refer to the section UNO Type Library for details about type information in the registry-based type library.

Writing the Specification
There are similarities between C++, CORBA IDL and UNOIDL, especially concerning the syntax and the general usage of the compiler. If you are familiar with reading C++ or CORBA IDL, you will be able to understand much of UNOIDL, as well.

As a first example, consider the IDL specification for the com.sun.star.bridge.XUnoUrlResolver interface. An idl file usually consists of module instructions followed by a type definition:

We will discuss this idl file step by step below, and we will write our own UNOIDL specification as soon as possible. The file specifying com.sun.star.bridge.XUnoUrlResolver is located in the idl folder of your SDK installation, /idl/com/sun/star/bridge/XUnoUrlResolver.idl.

UNOIDL definition file names have the extension. idl by convention. The descriptions must use the US ASCII character set without special characters and separate symbols by whitespace, i.e. blanks, tabs or linefeeds.

(For backwards compatibility, UNOIDL files may also include C-style preprocessor directives on lines starting with .  Such lines are ignored.)

Grouping Definitions in Modules
To avoid name clashes and allow for a better API structure, UNOIDL supports naming scopes. The corresponding instruction is module:

Instructions are only known inside the module mymodule for every type defined within the pair of braces of this module. Within each module, the type identifiers are unique. This makes an UNOIDL module similar to a Java package or a C++ namespace.

Modules may be nested. The following code shows the interface  contained in the module bridge that is contained in the module star, which is in turn contained in the module sun of the module com.

It is customary to write module names in lower case letters. Use your own module hierarchy for your IDL types. To contribute code to OpenOffice.org, use the. Discuss the name choice with the leader of the API project on www.openoffice.org to add to the latter modules. The  namespace mirrors the historical roots of OpenOffice.org in StarOffice and will probably be kept for compatibility purposes.

Types defined in UNOIDL modules have to be referenced using full-type or scoped names, that is, you must enter all modules your type is contained in and separate the modules by the scope operator. For instance, to reference  in another idl definition file, write.

Besides, modules have an advantage when it comes to generating language specific files. The tools cppumaker and javamaker automatically create subdirectories for every referenced module, if required. Headers and class definitions are kept in their own folders without any further effort.

One potential source of confusion is that UNOIDL and C++ use “ ” to separate the individual identifiers within a name, whereas UNO itself (e.g., in methods like com.sun.star.lang.XMultiComponentFactory:createInstanceWithContext ) and Java use “ ”.

Simple Types
Before we can go about defining our first interface, you need to know the simple types you may use in your interface definition. You should already be familiar with the simple UNO types from the chapters First Steps and Professional UNO. Since we have to use them in idl definition files, we repeat the type keywords and their meaning here.

Defining an Interface
Interfaces describe aspects of objects. To specify a new behavior for the component, start with an interface definition that comprises the methods offering the new behavior. Define a pair of plain get and set methods in a single step using the  instruction. Alternatively, choose to define your own operations with arbitrary arguments and exceptions by writing the method signature, and the exceptions the operation throws. We will first write a small interface definition with  instructions, then consider the   method in.

Let us assume we want to contribute an  component to OpenOffice.org to create thumbnail images for use in LibreOffice tables. There is already a com.sun.star.document.XFilter interface offering methods supporting file conversion. In addition, a method is required to get and set the source and target directories, and the size of the thumbnails to create. It is common practice that a service and its prime interface have corresponding names, so our component shall have an  interface with methods to do so through get and set operations.

Attributes
The  instruction creates these operations for the experimental interface definition:

Look at the specification for our  interface:

We protect the interface from being redefined using, then added   com.sun.star.uno.XInterface and the struct com.sun.star.awt.Size. These were found in the API reference using its global index. Our interface will be known in the  module, so it is nested in the corresponding module instructions.

Define an interface using the  instruction. It opens with the keyword, gives an interface name and derives the new interface from a parent interface (also called super interface). It then defines the interface body in braces. The  instruction concludes with a semicolon.

In this case, the introduced interface is. By convention, all interface identifiers start with an X. Every interface must inherit from the base interface for all UNO interfaces  or from one of its derived interfaces. The simple case of single inheritance is expressed by a colon  followed by the fully qualified name of the parent type. The fully qualified name of a UNOIDL type is its identifier, including all containing modules separated by the scope operator. Here we derive from  directly. If you want to declare a new interface that inherits from multiple interfaces, you do not use the colon notation, but instead list all inherited interfaces within the body of the new interface:

After the super interface the interface body begins. It may contain attribute and method declarations, and, in the case of a multiple-inheritance interface, the declaration of inherited interfaces. Consider the interface body of. It contains three attributes and no methods. Interface methods are discussed below.

An  declaration opens with the keyword   in square brackets, then it gives a known type and an identifier for the attribute, and concludes with a semicolon.

In our example, the  attributes named   and   and a   attribute known as   were defined:

During code generation in Java and C++, the attribute declaration leads to pairs of get and set methods. For instance, the Java interface generated by javamaker from this type description contains the following six methods:

As an option, define that an attribute cannot be changed from the outside using a  flag. To set this flag, write. The effect is that only a  method is created during code generation, but not a   method. Another option is to mark an attribute as bound; that flag is of interest when mapping interface attributes to properties, see Storing the Service Manager for Further Use and C++ Component.

Since OpenOffice.org 2.x, there can be exception specifications for attributes, individually for the operations of getting and setting an attribute:

If no exception specification is given, only runtime exceptions may be thrown.

Methods
When writing a real component, define the methods by providing their signature and the exceptions they throw in the idl file. Our  example above features a   method taking a UNO URL and throwing three exceptions.

The basic structure of a method is similar to C++ functions or Java methods. The method is defined giving a known return type, the operation name, an argument list in brackets  and if necessary, a list of the exceptions the method may throw. The argument list, the exception clause  and an optional   flag preceding the operation are special in UNOIDL.


 * Each argument in the argument list must commence with one of the direction flags,   or   before a known type and identifier for the argument is given. The direction flag specifies how the operation may use the argument:


 * {| class="wikitable"

!Direction Flags for Methods !Description
 * Specifies that the method shall evaluate the argument as input parameter, but it cannot change it.
 * Specifies that the argument does not parameterize the method, instead the method uses the argument as output parameter.
 * Specifies that the operation is parameterized by the argument and that the method uses the argument as output parameter as well.
 * }
 * Specifies that the argument does not parameterize the method, instead the method uses the argument as output parameter.
 * Specifies that the operation is parameterized by the argument and that the method uses the argument as output parameter as well.
 * }
 * Specifies that the operation is parameterized by the argument and that the method uses the argument as output parameter as well.
 * }
 * }


 * Try to avoid the  and   qualifiers, as they are awkward to handle in certain language bindings, like the Java language binding. The argument list can be empty. Multiple arguments must be separated by commas.


 * Exceptions are given through an optional  clause containing a comma-separated list of known exceptions given by their full name. The presence of a   clause means that only the listed exceptions, com.sun.star.uno.RuntimeException and their descendants may be thrown by the implementation. By specifying exceptions for methods, the implementer of your interface can return information to the caller, thus avoiding possible error conditions.

If you prepend a  flag to an operation, the operation can be executed asynchronously if the underlying method invocation system does support this feature. For example, a UNO Remote Protocol (URP) bridge is such a system that supports oneway calls. A  operation can not have a return value, or out or inout parameters. It must not throw other exceptions than.

Defining a Service
The new-style UNOIDL services combine interfaces and properties to specify a certain functionality. In addition, old-style services can include other services. For these purposes,,   and   declarations are used within service specifications. Usually, services are the basis for an object implementation, although there are old-style services in the LibreOffice API that only serve as a foundation for, or addition to, other services, but are not meant to be implemented by themselves.

We are ready to assemble our  service. Our service will read image files from a source directory and write shrunk versions of the found images to a destination directory. Our  interface offers the needed capabilities, together with the interface com.sun.star.document.XFilter that supports two methods:

A new-style service can only encompass one interface, so we need to combine  and   in a single, multiple-inheritance interface:

The  service specification is provided by the following code:

A new-style service is defined using the  declaration. A new-style service opens with the keyword, followed by a service name, a colon, the name of the interface supported by the service, and, finally, a semicolon. The first letter of the service name should be upper-case.

Old-style Services
An old-style service is much more complex. It opens with the keyword, followed by a service name and the service body in braces, and, finally, a semicolon. The body of a service can reference interfaces and services using  and   declarations, and it can identify properties supported by the service through   declarations.


 * keywords followed by interface names in a service body indicates that the service supports these interfaces. By default, the  forces the developer to implement this interface. To suggest an interface for a certain service, prepend an [optional] flag in front of the keyword  . This weakens the specification to a permission. An optional interface can be implemented. Use one interface declaration for each supported interface or give a comma-separated list of interfaces to be exported by a service. You must terminate the   declaration statement using a semicolon.


 * declaration statements in a service body include other services. The effect is that all interface and property definitions of the other services become part of the current service. A service reference can be optional using the  flag in front of the   keyword. Use one declaration per service or a comma-separated list for the services to reference. The   declaration ends with a semicolon.


 * declaration s describe qualities of a service that can be reached from the outside under a particular name and type. As opposed to interface attributes, these qualities are not considered to be a structural part of a service. Refer to the section Properties in the chapter Professional UNO to determine when to use interface attributes and when to introduce properties in a service . The  keyword must be enclosed in square brackets, and continue with a known type and a property identifier. Just like a service and an interface, make a property non-mandatory writing  . Besides optional,there is a number of other flags to use with properties. The following table shows all flags that can be used with  :


 * Several properties of the same type can be listed in one  declaration. Remember to add a semicolon at the end. Implement the interface com.sun.star.beans.XPropertySet when putting properties in your service, otherwise the properties specified will not work for others using the component.

The following UNOIDL snippet shows the service, the interfaces and the properties supported by the old-style service com.sun.star.text.TextDocument as defined in UNOIDL. Note the optional interfaces and the optional and read-only properties.

Defining a Sequence
A sequence in UNOIDL is an array containing a variable number of elements of the same UNOIDL type. The following is an example of a  term:

It starts with the keyword  and gives the element type enclosed in angle brackets. The element type must be a known type. A sequence type can be used as parameter, return value, property or struct member just like any other type. Sequences can also be nested, if necessary.

Defining a Struct
A struct is a compound type which puts together arbitrary UNOIDL types to form a new data type. Its member data are not encapsulated, rather they are publicly available. Structs are frequently used to handle related data easily, and the event structs broadcast to event listeners.

A plain struct instruction opens with the keyword, gives an identifier for the new struct type and has a struct body in braces. It is terminated by a semicolon. The struct body contains a list of struct member declarations that are defined by a known type and an identifier for the struct member. The member declarations must end with a semicolon, as well.

UNOIDL supports inheritance of struct types. Inheritance is expressed by a colon  followed by the full name of the parent type. A struct type recursively inherits all members of the parent  and their parents. For instance, derive from the struct com.sun.star.lang.EventObject to put additional information about new events into customized event objects to send to event listeners.

A new feature of OpenOffice.org 2.x were polymorphic struct types. A polymorphic struct type template is similar to a plain struct type, but it has one or more type parameters enclosed in angle brackets, and its members can have these parameters as types:

A polymorphic struct type template is not itself a UNO type - it has to be instantiated with actual type arguments to be used as a type:

Defining an Exception
An  type is a type that contains information about an error. If an operation detects an error that halts the normal process flow, it must raise an exception and send information about the error back to the caller through an  object. This causes the caller to interrupt its normal program flow as well and react according to the information received in the exception object. For details about exceptions and their implementation, refer to the chapters UNO Language Bindings and Exception Handling.

There are a number of exceptions to use. The exceptions should be sufficient in many cases, because a message string can be sent back to the caller. When defining an exception, do it in such a way that other developers could reuse it in their contexts.

An exception declaration opens with the keyword, gives an identifier for the new exception type and has an exception body in braces. It is terminated by a semicolon. The exception body contains a list of exception member declarations that are defined by a known type and an identifier for the exception member. The member declarations must end with a semicolon, as well.

Exceptions must be based on com.sun.star.uno.Exception or com.sun.star.uno.RuntimeException, directly or indirectly through derived exceptions of these two exceptions. com.sun.star.uno.Exception s can only be thrown in operations specified to raise them while com.sun.star.uno.RuntimeException s can always occur. Inheritance is expressed by a colon, followed by the full name of the parent type.

Predefining Values
Predefined values can be provided, so that implementers do not have to use cryptic numbers or other literal values. There are two kinds of predefined values, constants and enums. Constants can contain values of any basic UNO type, except void. The enums are automatically numbered long values.

Const and Constants
The  type is a container for   types. A  instruction opens with the keyword constants, gives an identifier for the new group of   values and has the body in braces. It terminates with a semicolon. The  body contains a list of   definitions that define the values of the members starting with the keyword   followed by a known type name and the identifier for the   in uppercase letters. Each  definition must assign a value to the   using an equals sign. The value must match the given type and can be an integer or floating point number, or a character, or a suitable  value or an arithmetic term based on the operators in the table below. The  definitions must end with a semicolon, as well.

Enum
An  type holds a group of predefined long values and maps them to meaningful symbols. It is equivalent to the enumeration type in C++. An  instruction opens with the keyword , gives an identifier for the new group of   values and has an   body in braces. It terminates with a semicolon. The  body contains a comma-separated list of symbols in uppercase letters that are automatically mapped to long values counting from zero, by default.

In this example, com.sun.star.style.ParagraphAdjust:LEFT corresponds to 0, com.sun.star.style.ParagraphAdjust:RIGHT corresponds to 1 and so forth.

An  member can also be set to a   value using the equals sign. All the following  values are then incremented starting from this value. If there is another assignment later in the code, the counting starts with that assignment:

Using Comments
Comments are code sections ignored by idlc. In UNOIDL, use C++ style comments. A double slash  marks the rest of the line as comment. Text enclosed between  and   is a comment that may span over multiple lines.

Based on the above, there are documentation comments that are extracted when idl files are processed with autodoc, the UNOIDL documentation generator. Instead of writing  or   to mark a plain comment, write   or   to create a documentation comment.

Our  sample idl file contains plain comments and documentation comments.

Note the additional  tag in the documentation comment pointing out that the service   implements the interface. This tag becomes a hyperlink in HTML documentation generated from this file. The chapter IDL Documentation Guidelines provides a comprehensive description for UNOIDL documentation comments.

Singleton
A  declaration defines a global name for a UNO object and determines that there can only be one instance of this object that must be reachable under this name. The singleton instance can be retrieved from the component context using the name of the. If the  has not been instantiated yet, the component context creates it. A new-style singleton declaration, that binds a singleton name to an object with a certain interface type, looks like this:

There are also old-style singletons, which reference (old-style) services instead of interfaces.

Published Entities
A newer feature of LibreOffice is the UNOIDL  keyword. If you mark a declaration (of a struct, interface, service, etc.) as published, you give the guarantee that you will not change the declaration in the future, so that clients of your API can depend on that. On the other hand, leaving a declaration unpublished is like a warning to your clients that the declared entity may change or even vanish in a future version of your API. The idlc will give an error if you try to use an unpublished entity in the declaration of a published one, as that would not make sense.

The LibreOffice API has always been intended to never change in incompatible ways. This is now reflected formally by publishing all those entities of the LibreOffice API that were already available in previous API versions. Some new additions to the API have been left unpublished, however, to document that they are probably not yet in their final form. When using such additions, keep in mind that you might need to adapt your code to work with future versions of LibreOffice. Generally, each part of the LibreOffice API should stabilize over time, however, and so each addition should eventually be published. Consider this as a means in attempting to make new functionality available as early as possible, and at the same time ensure that no APIs are fixed prematurely, before they have matured to a truly useful form.

Generating Source Code from UNOIDL Definitions
The type description provided in .idl files is used in the subsequent process to create type information for the service manager and to generate header and class files. Processing the UNOIDL definitions is a three-step process.


 * 1) Compile the .idl files using idlc. The result are .urd files (UNO reflection data) containing binary type descriptions.
 * 2) Merge the .urd files into a registry database using regmerge. The registry database files have the extension .rdb (registry database). They contain binary data describing types in a tree-like structure starting with / as the root. The default key for type descriptions is the /UCR key (UNO core reflection).
 * 3) Generate sources from registry files using javamaker or cppumaker. The tools javamaker and cppumaker map UNOIDL types to Java and C++ as described in the chapter UNO Language Bindings. The registries used by these tools must contain all types to map to the programming language used, including all types referenced in the type descriptions. Therefore, javamaker and cppumaker need the registry that was merged, but the entire office registry as well. LibreOffice comes with a complete registry database providing all types used by UNO at runtime. The SDK uses the database (type library) of an existing LibreOffice installation.

The following shows the necessary commands to create Java class files and C++ headers from .idl files in a simple setup under Linux. We assume the jars from /classes have been added to your CLASSPATH, the SDK is installed in /home/sdk, and /home/sdk/linux/bin is in the PATH environment variable, so that the UNO tools can be run directly. The project folder is /home/sdk/Thumbs and it contains the above .idl file.

After issuing these commands you have a registry database thumbs.rdb, two header files  and   (the first is the one you must include in the source files implementing your component), and a Java class file. (In versions of OpenOffice.org prior to 2.x, javamaker produced Java source files instead of class files; you therefore had to call  on the source files in an additional step.) You can run regview against   to see what regmerge has accomplished.

regview thumbs.rdb

The result for our interface  looks like this:

Source generation can be fully automated with makefiles. For details, see the sections Running and Debugging Java Components and C++ Component below. You are now ready to implement your own types and interfaces in a UNO component. The next section discusses the UNO core interfaces to implement in UNO components.

Component Architecture
UNO components are Java archive (JAR) files (Java components) or dynamic link libraries (C++ components), with the ability to instantiate objects which can integrate themselves into the UNO environment. For this purpose, components must contain certain static methods (Java) or export functions (C++) to be called by a UNO service manager. In the following, these methods are called component operations.

There must be a method to supply single-service factories for each object implemented in the component. Through this method, the service manager can get a single factory for a specific object and ask the factory to create the object contained in the component. Furthermore, there has to be a method which writes registration information about the component, which is used when a component is registered with the service manager. In C++, an additional function is necessary that informs the component loader about the compiler used to build the component.

The component operations are always necessary in components and they are language specific. Later, when Java and C++ are discussed, we will show how to write them.



The illustration shows a component which contains three implemented objects. Two of them, srv1 and srv2 implement a single service specification (Service1 and Service2), whereas srv3_4 supports two services at once (Service3 and Service4).

The objects implemented in a component must support a number of core UNO interfaces to be fully usable from all parts of the LibreOffice application. These core interfaces are discussed in the next section. The individual functionality of the objects is covered by the additional interfaces they export. Usually these interfaces are enclosed in a service specification.

Core Interfaces to Implement
It is important to know where the interfaces to implement are located. The interfaces here are located at the object implementations in the component. When writing UNO components, the desired methods have to be implemented into the application and also, the core interfaces used to enable communication with the UNO environment. Some of them are mandatory, but there are others to choose from.

The interfaces listed in the table above have been characterized here briefly. More descriptions of each interface are provided later, as well as if helpers are available and which conditions apply.

com.sun.star.uno.XInterface


 * The component will not work without it. The base interface  gives access to higher interfaces of the service and allows other objects to tell the service when it is no longer needed, so that it can destroy itself.


 * Usually developers do not call  explicitly, because it is called automatically by the language bindings when a reference to a component is retrieved through   or  . The counterpart   is called automatically when the reference goes out of scope in C++ or when the Java garbage collector throws away the object holding the reference.

com.sun.star.lang.XTypeProvider


 * This interface is used by scripting languages such as LibreOffice Basic to get type information. LibreOffice Basic cannot use the component without it.


 * It is possible that  and   (below) will be deprecated in the future, and that alternative, language-binding-specific mechanisms will be made available to query an object for its characteristics.

com.sun.star.lang.XServiceInfo


 * This interface is used by other objects to get information about the service implementation.

com.sun.star.uno.XWeak


 * This interface allows clients to keep a weak reference to the object. A weak reference does not prevent the object from being destroyed if another client keeps a hard reference to it, therefore it allows a hard reference to be retrieved again. The technique is used to avoid cyclic references. Even if the interface is not required by you, it could be implemented for a client that may want to establish a weak reference to an instance of your object.

com.sun.star.lang.XComponent


 * This interface is used if cyclic references can occur in the component holding another object and the other object is holding a reference to that component. It can be specified in the service description who shall destroy the object.

com.sun.star.lang.XInitialization


 * This interface is used to allow other objects to use  or   with the component. It should be implemented and the arguments processed in  :

com.sun.star.lang.XMain


 * This interface is for use with the uno executable to instantiate the component independently from the LibreOffice service manager.

com.sun.star.uno.XAggregation


 * This interfaces makes the implementation cooperate in an aggregation. If implemented, other objects can aggregate to the implementation. Aggregated objects behave as if they were one. If another object aggregates the component, it holds the component and delegates calls to it, so that the component seems to be one with the aggregating object.

com.sun.star.lang.XUnoTunnel


 * This interface provides a pointer to the component to another component in the same process. This can be achieved with .   should not be used by new components, because it is to be used for integration of existing implementations, if all else fails.

By now you should be able to decide which interfaces are interesting in your case. Sometimes the decision for or against an interface depends on the necessary effort as well. The following section discusses for each of the above interfaces how you can take advantage of pre-implemented helper classes in Java or C++, and what must happen in a possible implementation, no matter which language is used.

XInterface
All service implementations must implement com.sun.star.uno.XInterface. If a Java component is derived from a Java helper class that comes with the SDK, it supports  automatically. Otherwise, it is sufficient to add  or any other UNO interface to the implements list. The Java UNO runtime takes care of. In C++, there are helper classes to inherit that already implement. However, if  is to be implemented manually, consider the code below.

The IDL specification for com.sun.star.uno.XInterface looks like this:

Requirements for queryInterface
When  is called, the caller asks the implementation if it supports the interface specified by the type argument. The UNOIDL base type stores the name of a type and its com.sun.star.uno.TypeClass. The call must return an interface reference of the requested type if it is available or a void any if it is not. There are certain conditions a  implementation must meet:

Constant Behaviour


 * If  on a specific object has once returned a valid interface reference for a given type, it must always return a valid reference for any subsequent   call for the same type on this object. A query for   must always return the same reference.


 * If  on a specific object has once returned a void any for a given type, it must always return a void   for the same type.

Symmetry


 * If  for XBar on a reference xFoo returns a reference xBar, then   on reference xBar for type XFoo must return xFoo or calls made on the returned reference must be equivalent to calls to xFoo.

Object Identity


 * In C++, two objects are the same if their  are the same. The   for   will have to be called on both. In Java, check for the identity by calling the runtime function.

The reason for this specifications is that a UNO runtime environment may choose to cache  calls. The rules are identical to the rules of the function  in MS COM.

Reference Counting
The methods  and   handle the lifetime of the UNO object. This is discussed in detail in chapter Lifetime of UNO objects. Acquire and release must be implemented in a thread-safe fashion. This is demonstrated in C++ in the section about C++ components below.

XTypeProvider
Every UNO object should implement the com.sun.star.lang.XTypeProvider interface.

Some applications need to know which interfaces an UNO object supports, for example, the LibreOffice Basic engine or debugging tools, such as the InstanceInspector. The com.sun.star.lang.XTypeProvider interface was introduced to avoid going through all known interfaces calling  repetitively. The  interface is implemented by Java and C++ helper classes. If the  must be implemented manually, use the following methods:

The sections about Java and C++ components below show examples of  implementations.

Provided Types
The com.sun.star.lang.XTypeProvider:getTypes method must return a list of types for all interfaces that   provides. The LibreOffice Basic engine depends on this information to establish a list of method signatures that can be used with an object.

ImplementationID
For caching purposes, the  method has been introduced. The method must return a byte array containing an identifier for the implemented set of interfaces in this implementation class. It is important that one ID maps to one set of interfaces, but one set of interfaces can be known under multiple IDs. Every implementation class should generate a static ID.

XServiceInfo
Every service implementation should export the com.sun.star.lang.XServiceInfo interface. must be implemented manually, because only the programmer knows what services the implementation supports. The sections about Java and C++ components below show examples for  implementations.

This is how the IDL specification for  looks like:

Implementation Name
The method  provides access to the implementation name of a service implementation. The implementation name uniquely identifies one implementation of service specifications in a UNO object. The name can be chosen freely by the implementation alone, because it does not appear in IDL. However, the implementation should adhere to the following naming conventions:

If an object implements one single service, it can use the service name to derive an implementation name. Implementations of several services should use a name that describes the entire object.

If a  is called at the service manager using an implementation name, an instance of exactly that implementation is received. An implementation name is equivalent to a class name in Java. A Java component simply returns the fully qualified class name in.

Supported Service Names
The methods  and   deal with the availability of services in an implemented object. Note that the supported services are the services implemented in one class that supports these services, not the services of all implementations contained in the component file. In the illustration A Component implementing three UNO objects,  is exported by the implemented objects in a component, not by the component. That means, srv3_4 must support  and return "Service3" and "Service4" as supported service names.

The service name identifies a service as it was specified in IDL. If an object is instantiated at the service manager using the service name, an object that complies to the service specification is returned.

XWeak
A component supporting  offers other objects to hold a reference on itself without preventing it from being destroyed when it is no longer needed. Thus, cyclic references can be avoided easily. The chapter Lifetime of UNO Objects discusses this in detail. In Java, derive from the Java helper  to support. If a C++ component is derived from one of the  template classes as proposed in the section C++ Component, a   support is obtained, virtually for free. For the sake of completeness, this is the  specification:

XComponent
If the implementation holds a reference to another UNO object internally, there may be a problem of cyclic references that might prevent your component and the other object from being destroyed forever. If it is probable that the other object may hold a reference to your component, implement com.sun.star.lang.XComponent that contains a method. Chapter Lifetime of UNO Objects discusses the intricacies of this issue.

Supporting  in a C++ or Java component is simple, because there are helper classes to derive from that implement. The following code is an example if you must implement  manually.

The interface  specifies these operations:

uses the interface com.sun.star.lang.XEventListener :

Disposing of an XComponent
The idea behind  is that the object is instantiated by a third object that makes the third object the owner of first object. The owner is allowed to call. When the owner calls  at your object, it must do three things:


 * Release all references it holds.
 * Inform registered XEventListeners that it is being disposed of by calling their method.
 * Behave as passive as possible afterwards. If the implementation is called after being disposed, throw a com.sun.star.lang.DisposedException if you cannot fulfill the method specification.

That way the owner of  objects can dissolve a possible cyclic reference.

XInitialization
The interface com.sun.star.lang.XInitialization is usually implemented manually, because only the programmer knows how to initialize the object with arguments received from the service manager through  or. In Java,  is used as well, but know that the Java factory helper provides a shortcut that uses arguments without implementing   directly. The Java factory helper can pass arguments to the class constructor under certain conditions. Refer to the section Create Instance with Arguments for more information.

The specification for  looks like this:

An old-style UNOIDL service specification will typically specify which arguments and in which order are expected within the any sequence.

With the advent of new-style service specifications with explicit constructors, you can now declare explicitly what arguments can be passed to an object when creating it. The arguments listed in a constructor are exactly the arguments passed to  (the various language bindings currently use   internally to implement service constructors; that may change in the future, however).

XMain
The implementation of com.sun.star.lang.XMain is used for special cases. Its  operation is called by the uno executable. The section The UNO Executable below discusses the use of  and the uno executable in detail.

XAggregation
A concept called aggregation is commonly used to plug multiple objects together to form one single object at runtime. The main interface in this context is com.sun.star.uno.XAggregation. After plugging the objects together, the reference count and the  method is delegated from multiple slave objects to one master object.

It is a precondition that at the moment of aggregation, the slave object has a reference count of exactly one, which is the reference count of the master. Additionally, it does not work on proxy objects, because in Java, multiple proxy objects of the same interface of the same slave object might exist.

While aggregation allows more code reuse than implementation inheritance, the facts mentioned above, coupled with the implementation of independent objects makes programming prone to errors. Therefore the use of this concept is discourage and not explained here. For further information visit https://wiki.openoffice.org/wiki/Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno.

XUnoTunnel
The com.sun.star.lang.XUnoTunnel interface allows access to the  pointer of an object. This interface is used to cast a UNO interface that is coming back to its implementation class through a UNO method. Using this interface is a result of an unsatisfactory interface design, because it indicates that some functionality only works when non-UNO functions are used. In general, these objects cannot be replaced by a different implementation, because they undermine the general UNO interface concept. This interface can be understood as admittance to an already existing code that cannot be split into UNO components easily. If designing new services, do not use this interface.

The byte sequence contains an identifier that both the caller and implementer must know. The implementer returns this pointer of the object if the byte sequence is equal to the byte sequence previously stored in a static variable. The byte sequence is usually generated once per process per implementation.

Simple Component in Java
This section shows how to write Java components. The examples in this chapter are in the samples folder that was provided with the programmer's manual.

A Java component is a library of Java classes (a jar) containing objects that implement arbitrary UNO services. For a service implementation in Java, implement the necessary UNO core interfaces and the interfaces needed for your purpose. These could be existing interfaces or interfaces defined by using UNOIDL.

Besides these service implementations, Java components need two methods to instantiate the services they implement in a UNO environment: one to get single factories for each service implementation in the jar, and another one to write registration information into a registry database. These methods are called static component operations in the following:

The method that provides single factories for the service implementations in a component is :

In theory, a client obtains a single factory from a component by calling  on the component implementation directly. This is rarely done because in most cases service manager is used to get an instance of the service implementation. The service manager uses  at the component to get a factory for the requested service from the component, then asks this factory to create an instance of the one object the factory supports.

To find a requested service implementation, the service manager searches its registry database for the location of the component jar that contains this implementation. For this purpose, the component must have been registered beforehand. UNO components are able to write the necessary information on their own through a function that performs the registration and which can be called by the registration tool regcomp. The function has this signature:

These two methods work together to make the implementations in a component available to a service manager. The method  tells the service manager where to find an implementation while   enables the service manager to instantiate a service implementation, once found.

The necessary steps to write a component are:


 * 1) Define service implementation classes.
 * 2) Implement UNO core interfaces.
 * 3) Implement your own interfaces.
 * 4) Provide static component operations to make your component available to a service manager.

XInterface, XTypeProvider and XWeak
The LibreOffice Java UNO environment contains Java helper classes that implement the majority of the core interfaces that are implemented by UNO components. There are two helper classes:

The com.sun.star.lang.XServiceInfo is the only interface that should be implemented, but it is not part of the helpers.
 * The helper  is the minimal base class and implements ,   and.
 * The helper  that extends   and implements.

Use the naming conventions described in section XServiceInfo for the service implementation. Following the rules, a service  should be implemented in.

A possible class definition that uses  could look like this:

XServiceInfo
If the implementation only supports one service, use the following code to implement :

An implementation of more than one service in one UNO object is more complex. It has to return all supported service names in, furthermore it must check all supported service names in. Note that several services packaged in one component file are not discussed here, but objects supporting more than one service. Refer to A Component implementing three UNO objects for the implementation of srv3_4.

Implementing Your Own Interfaces
The functionality of a component is accessible only by its interfaces. When writing a component, choose one of the available API interfaces or define an interface. UNO types are used as method arguments to other UNO objects. Java does not support unsigned integer types, so their use is discouraged. In the chapter Using UNOIDL to Specify New Components, the  interface specification was written and an interface class file was created. Its implementation is straightforward, you create a class that implements your interfaces:

For the component to run, the new interface class file must be accessible to the Java Virtual Machine. Unlike stand-alone Java applications, it is not sufficient to set the CLASSPATH environment variable. Instead, the class path is passed to the VM when it is created. Prior to OpenOffice.org 1.1.0, one could modify the class path by editing the  entry of the java(.ini|rc) which was located in the folder '' \user\config. ''Another way was to use the Options dialog. To navigate to the class path settings, one had to expand the LibreOffice node in the tree on the left-hand side and chose Security. On the right-hand side, there was a field called User Classpath.

As of OpenOffice.org 1.1.0 the component, class files, and type library are packed into an extension, which is then registered by the pkgchk executable. And as of OpenOffice.org 2.0.0, the unopkg tool is used to do this. The jar files are then automatically added to the class path.

Providing a Single Factory Using Helper Method
The component must be able to create single factories for each service implementation it contains and return them in the static component operation. The LibreOffice Java UNO environment provides a Java class  that creates a default implementation of a single factory through its method. The following example could be written:

The  is contained in the jurt jar file. The  method takes as a first argument a   object. When  is called on the default factory, it creates an instance of that   using   on it and retrieves the implementation name through. The second argument is the service name. The  and   arguments were received in   and are passed to the.

The default factory created by the  expects a public constructor in the implementation class of the service and calls it when it instantiates the service implementation. The constructor can be a default constructor, or it can take a com.sun.star.uno.XComponentContext or a com.sun.star.lang.XMultiServiceFactory as an argument. Refer to Create Instance with Arguments for other arguments that are possible.

Java components are housed in jar files. When a component has been registered, the registry contains the name of the jar file, so that the service manager can find it. However, because a jar file can contain several class files, the service manager must be told which one contains the  method. That information has to be put into the jar's Manifest file, for example:

RegistrationClassName: org.openoffice.comp.test.ImageShrink

Write Registration Info Using Helper Method
UNO components have to be registered with the registry database of a service manager. In an office installation, this is the file types.rdb (up through OpenOffice.org 1.1.0, applicat.rdb) for all predefined services. A service manager can use this database to find the implementations for a service. For instance, if an instance of your component is created using the following call.

Using the given service or implementation name, the service manager looks up the location of the corresponding jar file in the registry and instantiates the component.

During the registration, a component writes the necessary information into the registry. The process to write the information is triggered externally when a client calls the  method at the component.

The caller passes an com.sun.star.registry.XRegistryKey interface that is used by the method to write the registry entries. Again, the  class offers a way to implement the method:

The writeRegistryServiceInfo method takes three arguments:


 * implementation name
 * service name
 * XRegistryKey

Use tools such as regcomp to register a component. This tool takes the path to the jar file containing the component as an argument. Since the jar can contain several classes, the class that implements the  method must be pointed out by means of the manifest. Again, the  entry determines the correct class. For example:

RegistrationClassName: org.openoffice.comp.test.ImageShrink

The above entry is also necessary to locate the class that provides, therefore the functions   and   have to be in the same class.

XInterface
As soon as the component implements any UNO interface, com.sun.star.uno.XInterface is included automatically. The Java interface definition generated by javamaker for com.sun.star.uno.XInterface only contains a  member used by Java UNO internally to store certain UNO type information:

Note that  does not have any methods, in contrast to its IDL description. That means, if  is added to a class definition, there is nothing to implement.

The method  is unnecessary in the implementation of a UNO object, because the Java UNO runtime environment obtains interface references without support from the UNO objects themselves. Within Java, the method  is used to obtain interfaces instead of calling com.sun.star.uno.XInterface:queryInterface, and the Java UNO language binding hands out interfaces for UNO objects to other processes on its own as well.

The methods  and   are used for reference counting and control the lifetime of an object, because the Java garbage collector does this, there is no reference counting in Java components.

XTypeProvider
Helper classes with default com.sun.star.lang.XTypeProvider implementations are still under development for Java. Meanwhile, every Java UNO object implementation can implement the  interface as shown in the following code. In your implementation, adjust :

The suggested implementation of the  method is not optimal, it uses the   of the first instance that initializes the static field. The future UNO helper class will improve this.

XComponent
is an optional interface that is useful when other objects hold references to the component. The notification mechanism of  enables listener objects to learn when the component stops to provide its services, so that the objects drop their references to the component. This enables the component to delete itself when its reference count drops to zero. From section Core Interfaces to Implement, there must be three things done when  is called at an  :

In Java, the object cannot be deleted, but the garbage collector will do this. It is sufficient to release all references that are currently being held to break the cyclic reference, and to call  on all com.sun.star.lang.XEventListener s.
 * Inform registered s that the object is being disposed of by calling their method.
 * Release all references the object holds, including all  objects.
 * On further calls to the component, throw a com.sun.star.lang.DisposedException in case the required task can not be fulfilled anymore, because the component was disposed.

The registration and removal of listener interfaces is a standard procedure in Java. Some IDEs even create the necessary methods automatically. The following example could be written:

Storing the Service Manager for Further Use
A component usually runs in the office process. There is no need to create an interprocess channel explicitly. A component does not have to create a service manager, because it is provided to the single factory of an implementation by the service manager during a call to  or. The single factory receives an  or an , and passes it to the corresponding constructor of the service implementation. From the component context, the implementation gets the service manager using  at the com.sun.star.uno.XComponentContext interface.

Create Instance with Arguments
A factory can create an instance of components and pass additional arguments. To do that, a client calls the  function of the com.sun.star.lang.XSingleServiceFactory interface or the   of the com.sun.star.lang.XSingleComponentFactory interface.

Both functions take an array of values as an argument. A component implements the com.sun.star.lang.XInitialization interface to receive the values. A factory passes the array on to the single method  supported by.

Alternatively, a component may also receive these arguments in its constructor. If a factory is written, determine exactly which arguments are provided by the factory when it instantiates the component. When using the FactoryHelper, implement the constructors with the following arguments:

The  automatically passes the array of arguments it received from the   call to the appropriate constructor. Therefore, it is not always necessary to implement  to use arguments.

Possible Structures for Java Components
The implementation of a component depends on the needs of the implementer. The following examples show some possible ways to assemble a component. There can be one implemented object or several implemented objects per component file.

One Implementation per Component File
There are additional options if implementing one service per component file:


 * Use a flat structure with the static component operations added to the service implementation class directly.
 * Reserve the class with the implementation name for the static component operation and use an inner class to implement the service.

Implementation Class with Component Operations
An implementation class contains the static component operations. The following sample implements an interface  in an implementation class  :

A component that implements only one service supporting  can be assembled in one class as follows:

The class implements the  interface. The IDL description and documentation provides information about its functionality. The class also contains the functions for factory creation and registration, therefore the manifest entry must read as follows:

RegistrationClassName: JavaComp.TestComponent

Implementation Class with Component Operations and Inner Implementation Class
To implement the component as inner class of the one that provides the service factory through, it must be a static inner class, otherwise the factory provided by the   cannot create the component. An example for an inner implementation class is located in the sample  provided with the SDK. The implementation of  and   is omitted here, because they act the same as in the implementation class with component operations above.

The manifest entry for this implementation structure again has to point to the class with the static component operations:

RegistrationClassName: com.sun.star.comp.demo.DemoComponent

Multiple Implementations per Component File
To assemble several service implementations in one component file, implement each service in its own class and add a separate class containing the static component operations. The following code sample features two services:  and   implementing the interfaces   and   with a separate static class   containing the component operations.

The following are the UNOIDL specifications for  and  :

implements :

implements. Note that it receives the component context and initialization arguments in its constructor.

implements  and  :

The corresponding manifest entry must point to the static class with the component operations, in this case :

RegistrationClassName: JavaComp.TestServiceProvider

Additional UNO Types
To make the Java UNO runtime more robust and efficient, each component is loaded with its own class loader, with one  at the root that takes care of loading all Java classes representing UNO types in such a way that they are available across the whole Java UNO runtime environment.

If a Java UNO component requires additional UNO types, it must use a  manifest entry to specify the location of the UNO types. The  is similar to the   manifest entry and can contain URLs of jars and directories that contain the Java classes that represent additional UNO types. The  evaluates the   manifest entry to ensure that the additional UNO types are available to the Java UNO environment. The  can have one of the following formats.
 * Current jar does not contain UNO types: UNO-Type-Path: (Note the final space character.)
 * Current jar contains UNO types: UNO-Type-Path: <>
 * Current jar brings other jars that contain UNO types: UNO-Type-Path: any/other/jar.jar yet/another/jar.jar
 * Current jar and other jars that the current jar uses contain UNO types: UNO-Type-Path: any/other/jar.jar <> yet/another/jar.jar

Running and Debugging Java Components
In order to run a Java component within an office, it needs to be registered first. During the process of registration, the location of the component, its service name and implementation name, are written into a registry database – the services.rdb.

Formerly the regcomp tool was used for registering components. However, it was superseded by pkgchk which came with OpenOffice.org 1.1.0 and later by unopkg which came with OpenOffice.org 2.0.0. For more details about unopkg refer to chapter Extensions.

By using regcomp you have the option of registering components so that the information is kept in a separate database (other then the services.rdb). This might come in handy if you do not want to clutter up the services.rdb while developing components. Then, however, the office needs to be told to use that .rdb, which is done by modifying the uno(.ini|rc).

If the component uses new types, then they must be made available to the office by merging the type information into the services.rdb. Again, you have the option of using a different database as long as the uno.(ini|rc) is modified accordingly. This step can be omitted if unopkg is being used.

The following is a step by step description of the registration process using regcomp:

Note, if errors are encountered, refer to the troubleshooting section at the end of this chapter.

Register Component File
This step creates a registry file that contains the location of the component file and all the necessary type information. To register, place a few files to the proper locations:


 * Copy the regcomp tool from the SDK distribution to /program.
 * Copy the component jar to /program/classes.
 * Copy the .rdb file containing the new types created to /program. If new types were not defined, dismiss this step. In this case, regcomp automatically creates a new rdb file with registration information.

On the command prompt, change to /program, then run regcomp with the following options. Line breaks were applied to improve readability, but the command must be entered in a single line:

$ regcomp -register -r .rdb -br services.rdb -br types.rdb -l com.sun.star.loader.Java -c file:////program/classes/.jar

For the  service whose type description was merged into thumbs.rdb, which is implemented in thumbs.jar, the corresponding command would be:

$ regcomp -register -r thumbs.rdb -br services.rdb -br types.rdb -l com.sun.star.loader.Java -c file:///i:/StarOffice6.0/program/classes/thumbs.jar

Instead of regcomp, there is also a Java tool to register components, however, it can only write to the same registry it reads from. It cannot be used to create a separate registry database. For details, see the section Deployment Options for Components.

Make Registration Available to OpenOffice.org
LibreOffice must be told to use the registry. Close all LibreOffice parts, including the Quickstarter that runs in the Windows task bar. Edit the file uno(.ini|rc) in /program as follows:

[Bootstrap] UNO_TYPES=$SYSBINDIR/types.rdb $SYSBINDIR/.rdb UNO_SERVICES=$SYSBINDIR/services.rdb $SYSBINDIR/.rdb

For details about the syntax of uno(.ini|rc) and alternative registration procedures, refer to the section Deployment Options for Components. If LibreOffice is restarted, the component should be available.

Test the Registration
A short LibreOffice Basic program indicates if the program runs went smoothly, by selecting Tools – Macro and entering a new macro name on the left, such as  and click New to create a new procedure. In the procedure, enter the appropriate code of the component. The test routine for  would be:

The result should be three dialogs showing the methods, properties and interfaces supported by the implementation. Note that the interface attributes do not appear as get/set methods, but as properties in Basic. If the dialogs do not show what is expected, refer to the section Troubleshooting.

Debugging
To increase turnaround cycles and source level debugging, configure the IDE to use GNU makefiles for code generation and prepare LibreOffice for Java debugging. If NetBeans are used, the following steps are necessary:

Support for GNU make
A NetBeans extension, available on makefile.netbeans.org, that adds basic support for GNU makefiles. When it is enabled, edit the makefile in the IDE and use the makefile to build. To install and enable this module, select Tools – Setup Wizard and click Next to go to the Module installation page. Find the module Makefiles and change the corresponding entry to True in the Enabled column. Finish using the setup wizard. If the module is not available in the installation, use Tools – Update Center to get the module from www.netbeans.org. A new entry, Makefile Support, appears in the online help when Help – Contents is selected. Makefile Support provides further configuration options. The settings Run a Makefile and Test a Makefile can be found in Tools – Options – Uncategorized – Compiler Types and – Execution Types.

Put the makefile into the project source folder that was mounted when the project was created. To build the project using the makefile, highlight the makefile in the Explorer and press.

Documentation for GNU make command-line options and syntax are available at www.gnu.org. The sample Thumbs in the samples folder along with this manual contains a makefile that with a few adjustments is useful for Java components.

Component Debugging
If NetBeans or Forte for Java is used, the Java Virtual Machine (JVM) that is launched by LibreOffice can be attached. Configure the JVM used by LibreOffice to listen for debugger connections. Prior to OpenOffice.org 2.x this was done by adding these lines to the java(.ini|rc) in /user/config:

-Xdebug -Xrunjdwp:transport=dt_socket,server=y,address=8000,suspend=n

As of OpenOffice.org 2.x, these lines are added in the options dialog: expand the LibreOffice node in the tree on the left-hand side and chose Java. On the right-hand side, push the Parameters button to open a dialog. In this dialog, enter the debug options as two separate entries. Note that the parameters have to be entered the same way as they would be provided on the command line when starting the Java executable. That is, retain the leading '-' and spaces, if necessary.

The last line causes the JVM to listen for a debugger on port 8000. The JVM starts listening as soon as it runs and does not wait until a debugger connects to the JVM. Launch the office and instantiate the Java component, so that the office invokes the JVM in listening mode.

Once a Java component is instantiated, the JVM keeps listening even if the component goes out of scope. Open the appropriate source file in the NetBeans editor and set breakpoints as needed. Choose Debug - Attach, select Java Platform Debugger Architecture (JPDA) as debugger type and SocketAttach (Attaches by socket to other VMs) as the connector. The Host should be localhost and the Port must be 8000. Click OK to connect the Java Debugger to the JVM the office has started previously step.

Once the debugger connects to the running JVM, NetBeans switches to debug mode, the output windows shows a message that a connection on port 8000 is established and threads are visible, as if the debugging was local. If necessary, start your component once again. As soon as the component reaches a breakpoint in the source code, the source editor window opens with the breakpoint highlighted by a green arrow.

The Java Environment in LibreOffice
When UNO components written in Java are to be used within the office suite, the office suite has to be configured to use the appropriate JRE. For information on the supported JREs see Documentation/FAQ/Installation/Which version of Java do I need%3F.

LibreOffice
Since the release of OpenOffice.org 3.4.0 you can set the JRE from the menu Tools->Options : tree node OpenOffice->Java.

OpenOffice.org 2.x
In OpenOffice.org 2.x there is no java(.ini|rc) anymore. All basic Java settings are set in the options dialog: tree node LibreOffice->Java. The Parameters dialog can be used to specify the debug options and other arguments.

For applets there are still a few settings on the security panel (tree node LibreOffice->Security).

Versions prior to OpenOffice.org 2.x
Prior to OpenOffice.org 2.x, this configuration happened during the installation, when the Java setup was performed. Then, a user could choose a Java Runtime Environment or choose to install a JRE. After installing the office, the selected JRE could still be changed with the jvmsetup program, which was located in the program folder. The data for running the Java Virtual Machine was stored in the java(.ini|rc) file and other configuration files.

In an office with a lower version than 2.x, the java(.ini|rc) is located in the  \user\config directory. A client can use that file to pass additional properties to the Java Virtual Machine, which are then available as system properties. For example, to pass the property, invoke Java like this:

java -DMyAge=30 RunClass

If you want to have that system property accessible by your Java component you can put that property into java(ini|rc) within the  section. For example:

To debug a Java component, it is necessary to start the JVM with additional parameters. The parameters can be put in the java.ini the same way as they would appear on the command-line. For example, add those lines to the  section:

-Xdebug -Xrunjdwp:transport=dt_socket,server=y,address=8000

More about debugging can be found in the JDK documentation and in the LibreOffice Software Development Kit.

Java components are also affected by the following configuration settings. They can be changed in the Tools - Options dialog. In the dialog, expand the OpenOffice node on the left-hand side and choose Security. This brings up a new pane on the right-hand side that allows Java specific settings:

Troubleshooting
If the component encounters problems, review the following checklist to check if the component is configured correctly.

Check Registry Keys
To check if the registry database is correctly set up, run regview against the three keys that make up a registration in the /UCR, /SERVICES and /IMPLEMENTATIONS branch of a registry database. The following examples show how to read the appropriate keys and how a proper configuration should look. In our example, service, and the key /UCR/org/openoffice/test/XImageShrink contain the type information specified in UNOIDL (the exact output from regview might differ between versions of LibreOffice):

The /SERVICES/org.openoffice.test.ImageShrink key must point to the implementation name  that was chosen for this service:

Finally, the /IMPLEMENTATIONS/org.openoffice.comp.test.ImageShrink key must contain the loader and the location of the component jar:

If the UCR key is missing, the problem is with regmerge. The most probable cause are missing .urd files. Be careful when writing the makefile. If .urd files are missing when regmerge is launched by the makefile, regmerge continues and creates a barebone .rdb file, sometimes without any type info.

If regview can not find the /SERVICES and /IMPLEMENTATIONS keys or they have the wrong content, the problem occurred when regcomp was run. This can be caused by wrong path names in the regcomp arguments.

Also, a wrong  setup in java(.ini|rc) (prior to OpenOffice.org 2.x could be the cause of regcomp error messages about missing classes. Check what the   entry in java(.ini|rc) specifies for the Java UNO runtime jars.

Ensure that regcomp is being run from the current directory when registering Java components. In addition, ensure /program is the current folder when regcomp is run. Verify that regcomp is in the current folder.

Check the Java VM settings
Whenever the VM service is instantiated by LibreOffice, it uses the Java configuration settings in LibreOffice. This happens during the registration of Java components, therefore make sure that Java is enabled. Choose Tools-Options in LibreOffice, so that the dialog appears. Expand the OpenOffice node and select Security. Select the Enable checkbox in the Java section and click OK.

Check the Manifest
Make sure the manifest file contains the correct entry for the registration class name. The file must contain the following line:

RegistrationClassName: <full name of package and class>

Please make sure that the manifest file ends up with a new line. The registration class name must be the one that implements the  and   methods. The  to be entered in the manifest for our example is.

Adjust CLASSPATH for Additional Classes
LibreOffice maintains its own system classpath and a user classpath when it starts the Java VM for Java components. The jar file that contains the service implementation is not required in the system or user classpath. If a component depends on jar files or classes that are not part of the Java UNO runtime jars, then they must be put on the classpath. This can be achieved by editing the classpath in the options dialog (Tools – Options – OpenOffice – Security).

Disable Debug Options
If the debug options (-Xdebug, -Xrunjdwp) are in the java(.ini|rc) (prior to OpenOffice 2.x) file, disable them by putting semicolons at the beginning of the respective lines. For OpenOffice.org 2.x and later, make sure the debug options are removed in the Parameters dialog. This dialog can be found in the options dialog (Tools – Options – OpenOffice – Java). The regcomp or tool or the Extension Manager may hang, because the JVM is waiting for a debugger to be attached.

C++ Component
The first step for the C++ component is to define a language-independent interface, so that the UNO object can communicate with others. The IDL specification for the component defines one interface  and two old-style services implementing this interface (if new-style services were used instead, the example would not be much different). In addition, the second service called  implements the com.sun.star.lang.XInitialization interface, so that   can be instantiated with arguments passed to it during runtime.

This IDL is compiled to produce a binary type library file (.urd file), by executing the following commands. The types are compiled and merged into a registry simple_component.rdb, that will be linked into the LibreOffice installation later.

$ idlc -I<SDK>/idl some.idl $ regmerge simple_component.rdb /UCR some.urd

The cppumaker tool must be used to map IDL to C++:

$ cppumaker -BUCR -Tmy_module.XSomething /program/types.rdb simple_component.rdb

For each given type, a pair of header files is generated, a .hdl and a .hpp file. To avoid conflicts, all C++ declarations of the type are in the .hdl and all definitions, such as constructors, are in the .hpp file. The .hpp is the one to include for any type used in C++.

The next step is to implement the core interfaces, and the implementation of the component operations,   and   with or without helper methods.

XInterface, XTypeProvider and XWeak
The SDK offers helpers for ease of developing. There are implementation helper template classes that deal with the implementation of com.sun.star.uno.XInterface and com.sun.star.lang.XTypeProvider, as well as com.sun.star.uno.XWeak. These classes let you focus on the interfaces you want to implement.

The implementation of  uses the   helper. The "3" stands for the number of interfaces to implement. The class declaration inherits from this template class which takes the interfaces to implement as template parameters.

The next section focuses on coding com.sun.star.lang.XServiceInfo, com.sun.star.lang.XInitialization and the sample interface.

The cppuhelper shared library provides additional implementation helper classes, for example, supporting com.sun.star.lang.XComponent. Browse the ::cppu namespace in the C++ reference of the SDK or on www.openoffice.org/udk/.

XServiceInfo
An UNO service implementation supports com.sun.star.lang.XServiceInfo providing information about its implementation name and supported services. The implementation name is a unique name referencing the specific implementation. In this case,  and   respectively. The implementation name is used later when registering the implementation into the simple_component.rdb registry used for LibreOffice. It links a service name entry to one implementation, because there may be more than one implementation. Multiple implementations of the same service may have different characteristics, such as runtime behavior and memory footprint.

Our service instance has to support the com.sun.star.lang.XServiceInfo interface. This interface has three methods, and can be coded for one supported service as follows:

Implementing your own Interfaces
For the  interface, add a string to be returned that informs the caller when   was called successfully.

Providing a Single Factory Using a Helper Method
C++ component libraries must export an external "C" function called  that supplies a factory object for the given implementation. Use  to create this function. The declarations for it are included through cppuhelper/implementationentry.hxx.

The  method appears at the end of the following listing. This method assumes that the component includes a static  array , which contains a number of function pointers. The listing shows how to write the component, so that the function pointers for all services of a multi-service component are correctly initialized.

The static variable  defines a null-terminated array of entries concerning the service implementations of the shared library. A service implementation entry consists of function pointers for


 * object creation:
 * implementation name:
 * supported service names:
 * factory helper to be used:

The last two values are reserved for future use and therefore can be 0.

Write Registration Info Using a Helper Method
Use  to implement. This function is called by regcomp during the registration process.

Note that  uses the same array of   structs as  ,that is,.

Provide Implementation Environment
The function called  tells the shared library component loader which compiler was used to build the library. This information is required if different components have been compiled with different compilers. A specific C++-compiler is called an environment. If different compilers were used, the loader has to bridge interfaces from one compiler environment to another, building the infrastructure of communication between those objects. It is mandatory to have the appropriate C++ bridges installed into the UNO runtime. In most cases, the function mentioned above can be implemented this way:

The macro  is a C string defined by the compiling environment, if you use the SDK compiling environment. For example, when compiling with the Microsoft Visual C++ compiler, it defines to " ", but when compiling with the GNU gcc 3, it defines to " ".

Implementing without Helpers
In the following section, possible implementations without helpers are presented. This is useful if more interfaces are to be implemented than planned by the helper templates. The helper templates only allow up to ten interfaces. Also included in this section is how the core interfaces work.

XInterface Implementation
Object lifetime is controlled through the common base interface com.sun.star.uno.XInterface methods  and. These are implemented using reference-counting, that is, upon each, the counter is incremented and upon each  , it is decreased. On last decrement, the object dies. Programming in a thread-safe manner, the modification of this counter member variable is commonly performed by a pair of  library functions called   and   (include osl/interlck.h).

In the  method, interface pointers have to be provided to the interfaces of the object. That means, cast this to the respective pure virtual C++ class generated by the cppumaker tool for the interfaces. All supported interfaces must be returned, including inherited interfaces like.

XTypeProvider Implementation
When implementing the com.sun.star.lang.XTypeProvider interface, two methods have to be coded. The first one,  provides all implemented types of the implementation, excluding base types, such as com.sun.star.uno.XInterface. The second one,  provides a unique ID for this set of interfaces. A thread-safe implementation of the above mentioned looks like the following example:

Providing a Single Factory
The function  provides a single object factory for the requested implementation, that is, it provides a factory that creates object instances of one of the service implementations. Using a helper from cppuhelper/factory.hxx, this is implemented quickly in the following code:

In the example above, note the function  that is called by the factory object when it needs to instantiate the class. A component context com.sun.star.uno.XComponentContext is provided to the function, which may be passed to the constructor of.

Write Registration Info
The function  is called by the shared library component loader upon registering the component into a registry database file (.rdb). The component writes information about objects it can instantiate into the registry when it is called by regcomp.

Storing the Service Manager for Further Use
The single factories expect a static  function. For instance,  takes a reference to the component context and instantiates the implementation class using new. A constructor can be written for  that expects a reference to a com.sun.star.uno.XComponentContext and stores the reference in the instance for further use.

Create Instance with Arguments
If the service should be raised passing arguments through com.sun.star.lang.XMultiComponentFactory:createInstanceWithArgumentsAndContext and com.sun.star.lang.XMultiServiceFactory:createInstanceWithArguments, it has to implement the interface com.sun.star.lang.XInitialization. The second service  implements it, expecting a single string as an argument.

Multiple Components in One Dynamic Link Library
The construction of C++ components allows putting as many service implementations into a component file as desired. Ensure that the component operations are implemented in such a way that  and   handle all services correctly. Refer to the sample component  to see an example on how to implement two services in one link library.

Build Process
For details about building component code, see the gnu makefile. It uses a number of platform dependent variables used in the SDK that are included from <SDK>/settings/settings.mk. For simplicity, details are omitted here, and the build process is just sketched in eight steps:


 * 1) The UNOIDL compiler compiles the .idl file some.idl into an urd file.
 * 2) The resulting binary .urd files are merged into a new simple_component.rdb.
 * 3) The tool xml2cmp parses the xml component description simple_component.xml for types needed for compiling. This file describes the service implementation(s) for deployment, such as the purpose of the implementation(s) and used types. Visit https://www.openoffice.org/udk/common/man/module_description.html for details about the syntax of these XML files.
 * 4) The types parsed in step 3 are passed to cppumaker, which generates the appropriate header pairs into the output include directory using simple_component.rdb and the LibreOffice type library types.rdb that is stored in the program directory of your LibreOffice installation.

<li>The source files service1_impl.cxx and service2_impl.cxx are compiled.</li> <li>The shared library is linked out of object files, linking dynamically to the UNO base libraries sal, cppu and cppuhelper. The shared library's name is libsimple_component.so on Unix and simple_component.dll on Windows.</li> </ol>

<li>The shared library component is registered into simple_component.rdb. This can also be done manually running</li> </ol>

$ regcomp -register -r simple_component.rdb -c simple_component.dll

Test Registration and Use
The component's registry simple_component.rdb has entries for the registered service implementations. If the library is registered successfully, run:

$ regview simple_component.rdb

The result should look similar to the following:

LibreOffice recognizes registry files being inserted into the unorc file (on Unix, uno.ini on Windows) in the program directory of your LibreOffice installation. Extend the types and services in that file by simple_component.rdb. The given file has to be an absolute file URL, but if the rdb is copied to the LibreOffice program directory, a $ORIGIN macro can be used, as shown in the following unorc file:

Second, when running LibreOffice, extend the PATH (Windows) or LD_LIBRARY_PATH (Unix), including the output path of the build, so that the loader finds the component. If the shared library is copied to the program directory or a link is created inside the program directory (Unix only), do not extend the path.

Launching the test component inside a LibreOffice Basic script is simple to do, as shown in the following code:

This procedure instantiates the service implementations and performs calls on their interfaces. The return value of the  call is brought up in message boxes. The Basic object property  retrieves its information through the com.sun.star.lang.XTypeProvider interfaces of the objects.

Integrating Components into LibreOffice
If a component needs to be called from the LibreOffice user interface, it must be able to take part in the communication between the UI layer and the application objects. LibreOffice uses command URLs for this purpose. When a user chooses an item in the user interface, a command URL is dispatched to the application framework and processed in a chain of responsibility until an object accepts the command and executes it, thus consuming the command URL. This mechanism is known as the dispatch framework, it is covered in detail in chapter Using the Dispatch Framework.

From version OpenOffice.org 1.1.0, LibreOffice provides user interface support for custom components by two basic mechanisms:


 * Components can be enabled to process command URLs. There are two ways to accomplish this. You can either make them a protocol handler for command URLs or integrate them into the job execution environment of LibreOffice. The protocol handler technique is simple, but it can only be used with command URLs in the dispatch framework. A component for the job execution environment can be used with or without command URLs, and has comprehensive support when it comes to configuration, job environment, and lifetime issues.


 * The user interface can be adjusted to new components. On the one hand, you can add new menus and toolbar items and configure them to send the command URLs needed for your component. On the other hand, it is possible to disable existing commands. All this is possible by adding certain files to the extension. When users of your component install the extension, the GUI is adjusted automatically.

The left side of the illustration below shows the two possibilities for processing command URLs: either custom protocol handlers or the specialized job protocol. On the right, you see the job execution environment, which is used by the job protocol, but can also be used without command URLs from any source code.



This section describes how to use these mechanisms. It discusses protocol handlers and jobs, then describes how to customize the LibreOffice user interface for components.

Protocol Handler
The dispatch framework binds user interface controls, such as menu or toolbar items, to the functionality of LibreOffice. Every function that is reachable in the user interface is described by a command URL and corresponding parameters.

The protocol handler mechanism is an API that enables programmers to add arbitrary URL schemas to the existing set of command URLs by writing additional protocol handlers for them. Such a protocol handler must be implemented as a UNO component and registered in the LibreOffice configuration for the new URL schema.

Overview
To issue a command URL, the first step is to locate a dispatch object that is responsible for the URL. Start with the frame that contains the document for which the command is meant. Its interface method com.sun.star.frame.XDispatchProvider:queryDispatch is called with a URL and special search parameters to locate the correct target. This request is passed through the following instances:

The list shows that the protocol handler will only be used if the URL has not been called before. Because targeting has already been done, it is clear that the command will run in the located target frame environment, which is usually " ".

A protocol handler decides by itself if it returns a valid dispatch object, that is, it is asked to agree with the given request by the dispatch framework. If a dispatch object is returned, the requester can use it to dispatch the URL by calling its  method.

Implementation
A protocol handler implementation must follow the service definition com.sun.star.frame.ProtocolHandler. At least the interface com.sun.star.frame.XDispatchProvider must be supported.



The interface  supports two methods:

The protocol handler is asked for its agreement to execute a given URL by a call to the interface method com.sun.star.frame.XDispatchProvider:queryDispatch. The incoming URL should be parsed and validated. If the URL is valid and the protocol handler is able to handle it, it should return a dispatch object, thus indicating that it accepts the request.

The dispatch object must support the interface com.sun.star.frame.XDispatch with the methods

Optionally, the dispatch object can support the interface com.sun.star.frame.XNotifyingDispatch, which derives from  and introduces a new method. This interface is preferred if it is present.

A basic protocol handler is free to implement XDispatch itself, so it can simply return itself in the  implementation. But it is advisable to return specialized helper dispatch objects instead of the protocol handler instance. This helps to decrease the complexity of status updates. It is easier to notify status listeners for a single-use dispatch object instead of multi-use dispatch objects, which have to distinguish the URLs given in  all the time.

A protocol handler can support the interface com.sun.star.lang.XInitialization if it wants to be initialized with a com.sun.star.frame.Frame environment to work with. contains one method:

A protocol handler is generally used in a well known com.sun.star.frame.Frame context, therefore the dispatch framework always passes this frame context through  as the first argument, if   is present. Its com.sun.star.frame.XFrame interface provides access to the controller, from which you can get the document model and have a good starting point to work with the document.

The illustration below shows how to get to the controller and the document model from an XFrame interface. The chapter Using the Component Framework describes the usage of frames, controllers and models in more detail.



The opportunity to deny a  call allows you to register a protocol handler for a URL schema using wildcards, and to accept only a subset of all possible URLs. That way the handler object can validate incoming URLs and reject them if they appear to be invalid. However, this feature should not be used to register different protocol handlers for the same URL schema and accept different subsets by different handler objects, because it would be very difficult to avoid ambiguities.

Since a protocol handler is a UNO component, it must contain the component operations needed by a UNO service manager. These operations are certain static methods in Java or export functions in C++. It also has to implement the core interfaces used to enable communication with UNO and the application environment. For more information on the component operations and core interfaces, please see Component Architecture and Core Interfaces to Implement.

Java Protocol Handler - vnd.sun.star.framework.ExampleHandler
The following example shows a simple protocol handler implementation in Java. For simplicity, the component operations are omitted.

C++ Protocol Handler - org.openoffice.Office.addon.example
The next example shows a protocol handler in C++. The section Add-Ons below will integrate this example handler into the graphical user interface of LibreOffice.

The following code shows the UNO component operations that must be implemented in a C++ protocol handler example. The three C functions return vital information to the UNO environment:


 * tells the shared library component loader which compiler was used to build the library.
 * is called during the registration process by the registration tool regcomp, or indirectly when you use the Extension Manager.
 * provides a single service factory for the requested implementation. This factory can be asked to create an arbitrary number of instances for only one service specification, therefore it is called a single service factory, as opposed to a multi-service factory, where you can order instances for many different service specifications. (A single service factory has nothing to do with a singleton).

The C++ protocol handler in the example has the implementation name. It supports the URL protocol schema org.openoffice.Office.addon.example: and provides three different URL commands:,   and.

The protocol handler implements the com.sun.star.frame.XDispatch interface, so it can return a reference to itself when it is queried for a dispatch object that matches the given URL.

The implementation of the  method below shows how the supported commands are routed inside the protocol handler. Based on the path part of the URL, a simple message box displays which function has been called. The message box is implemented using the UNO toolkit and uses the container windows of the given frame as parent window.

Configuration
A protocol handler needs configuration entries, which provide the framework with the necessary information to find the handler. The schema of the configuration branch org.openoffice.Office.ProtocolHandler defines how to bind handler instances to their URL schemas:

Each set node entry specifies one protocol handler, using its UNO implementation name. The only property it has is the Protocols item. Its type must be  and it contains a list of URL schemas bound to the handler. Wildcards are allowed, otherwise the entire string must match the dispatched URL.

Configuration for vnd.sun.star.framework.ExampleHandler
The following example ProtocolHandler.xcu contains the protocol handler configuration for the example's Java protocol handler:

The example adds two new URL protocols using wildcards:

myProtocol_1://* myProtocol_2://*

Both protocols are bound to the handler implementation. Note that this must be the implementation name of the handler, not the name of the service com.sun.star.frame.ProtocolHandler it implements. Because all implementations of the service com.sun.star.frame.ProtocolHandler share the same UNO service name, you cannot use this name in the configuration files.

To prevent ambiguous implementation names, the following naming schema for implementation names is frequently used:

vnd.&lt;namespace_of_company&gt;.&lt;namespace_of_implementation&gt;.&lt;class_name&gt;

e.g.

&lt;namespace_of_company&gt;= sun.star &lt;namespace_of_implementation&gt;= framework &lt;class_name&gt;= ExampleHandler

An alternative would be the naming convention proposed in XServiceInfo:

&lt;namespace_of_creator&gt;.comp.&lt;namespace_of_implementation&gt;.&lt;class_name&gt;

e.g.

All of these conventions are proposals; what matters is:


 * use the implementation name in the configuration file, not the general service name "com.sun.star.frame.ProtocolHandler"
 * be careful to choose an implementation name that is likely to be unique, and be aware that your handler ceases to function when another developer adds a handler with the same name.

Configuration for org.openoffice.Office.addon.example
The following ProtocolHandler.xcu file configures the example's C++ protocol handler with the implementation name org.openoffice.Office.addon.example in the configuration branch org.openoffice.Office.ProtocolHandler following the same schema.

The configuration adds one new URL protocol using wildcards:

org.openoffice.Office.addon.example:*

Based on this URL protocol, the C++ protocol handler can route, for example, a dispatched URL

org.openoffice.Office.addon.example:Function1

to the corresponding target routine. See the implementation of the  method in the   interface of the C++ source fragment above.

Installation
When the office finds a protocol handler implementation for a URL in the configuration files, it asks the global service manager to instantiate that implementation. All components must be registered with the service manager before they can be instantiated. This happens automatically when an extension is being installed (see chapter Extensions).

The easiest method to configure and register a new protocol handler in a single step is therefore to use the Extension Manager. An extension for the example protocol handler could contain the following directory structure:

ExampleHandler.oxt: META-INF/manifest.xml ProtocolHandler.xcu windows.plt/ examplehandler.dll solaris_sparc.plt/ libexamplehandler.so     linux_x86.plt/ libexamplehandler.so

The .xcu file can go directly into the root of the extension, the shared libraries for the various platforms go to their respective .plt directories. Both the .xcu and the libraries have to be referenced in the manifest.xml.

The package installation is as simple as changing to the <OfficePath>/program directory with a command-line shell and running

$ unopkg add /foo/bar/ExampleHandler.oxt

or simply starting the Extension Manager in your office to install the extensions via the UI.

For an detailed explanation of the extension structure please refer to Extensions.

Jobs
A job in LibreOffice is a UNO component that can be executed by the job execution environment upon an event. It can read and write its own set of configuration data in the configuration branch org.openoffice.Office.Jobs, and it can be activated and deactivated from a certain point in time using special time stamps. It may be started with or without an environment, and it is protected against termination and lifetime issues.

The event that starts a job can be triggered by:


 * any code in LibreOffice that detects a defined state at runtime and passes an event string to the service com.sun.star.task.JobExecutor through its interface method com.sun.star.task.XJobExecutor:trigger . The job executor looks in the configuration of LibreOffice if there are any jobs registered for this event and executes them.


 * the global document event broadcaster


 * the dispatch framework, which provides for a vnd.star.sun.job: URL schema to start jobs using a command URL. This URL schema can execute jobs in three different ways: it can issue an event for job components that are configured to wait for it, it can call a component by an alias that has been given to the component in the configuration or it can execute a job component directly by its implementation name.

If you call  at the job executor or employ the global event broadcaster, the office needs a valid set of configuration data for every job you want to run. The third approach, to use a vnd.star.sun.job: command URL, works with or without prior configuration.

The illustration below shows an example job that counts how many times it has been triggered by an event and deactivates itself when it has been executed twice. It uses its own job-specific configuration layer to store the number of times it has been invoked. This value is passed to each newly created job instance as an initialization argument, and can be checked and written back to the configuration. When the counter exceeds two, the job uses the special deactivation feature of the job execution environment. Each job can have a user timestamp and administrator timestamp to control activation and deactivation. When a job is deactivated, the execution environment updates the user timestamp value, so that subsequent events do not start this job again. It can be enabled by a newer time stamp value in the administration layer.



Execution Environment
Jobs are executed in a job execution environment, which handles a number of tasks and problems that can occur when jobs are executed. In particular,


 * it initializes the job with all necessary data
 * it starts the job using the correct interfaces
 * it keeps the job alive by acquiring a UNO reference
 * it waits until the job finishes its work, including listening for asynchronous jobs
 * it updates the configuration of a job after it has finished
 * it informs listeners about the execution
 * it protects the job from office termination, or informs it when it is impossible to veto termination

For this purpose, the job execution environment creates special wrapper objects for jobs. This wrapper object implements mechanisms to support lifetime control. The wrapper vetoes termination of the com.sun.star.frame.Desktop and the closing of frames that contain document models as long as there are dependent active jobs. It might also register as a com.sun.star.util.XCloseListener at a com.sun.star.frame.Frame or com.sun.star.document.OfficeDocument to handle the close communication on behalf of the job. It also listens for asynchronous job instances, and it is responsible for updates to the configuration data after a job has finished (see Returning Results).

A central problem of external components in LibreOffice is their lifetime control. Every external component must deal with the possibility that the environment will terminate. It is not efficient to implement lifetime strategies in every job, so the job execution environment takes care of this problem. That way, a job can execute, while difficult situations are handled by the execution environment.

Another advantage of this approach is that it ensures future compatibility. If the mechanism changes in the future, termination is detected and prevented, and it is unnecessary to adapt every existing job implementation.

Implementation
A job must implement the service com.sun.star.task.Job if it needs to block the thread in which it is executed or com.sun.star.task.AsyncJob if the current state of the office is unimportant for the job. The service that a job implementation supports is detected at runtime. If both are available, the synchronous service com.sun.star.task.Job is preferred by the job execution environment.



A synchronous job must not make assumptions about the environment, neither that it is the only job that runs currently nor that another object waits for its results. Only the thread context of a synchronous job is blocked until the job finishes its work.

An asynchronous job is not allowed to use threads internally, because LibreOffice needs to control thread creation. How asynchronous jobs are executed is an implementation detail of the global job execution environment.

Jobs that need a user interface must proceed with care, so that they do not interfere with the message loop of LibreOffice. The following rules apply:


 * You cannot display any user interface from a synchronous job, because repaint errors and other threading issues will occur.
 * The easiest way to have a user interface for an asynchronous job is to use a non-modal dialog. If you need a modal dialog to get user input, problems can occur. The best way is to use the frame reference that is part of the job environment initialization data, and to get its container window as a parent window. This parent window can be used to create a dialog with the user interface toolkit com.sun.star.awt.Toolkit . The C++ protocol handler discussed in Implementation shows how a modal message box uses this approach.
 * Using a native toolkit or the Java AWT for your GUI can lead to a non-painting LibreOffice. To avoid this, the user interface must be non-modal and the implementation must allow the office to abort the job by supporting com.sun.star.lang.XComponent or com.sun.star.util.XCloseable.

The optional interfaces com.sun.star.lang.XComponent or com.sun.star.util.XCloseable should be supported so that jobs can be disposed of in a controlled manner. When these interfaces are present, the execution environment can call  or   rather than waiting for a job to finish. Otherwise LibreOffice must wait until the job is done. Invisible jobs can be especially problematic, because they cannot be recognized as the reason why LibreOffice refuses to exit.

Initialization
A job is initialized by a call to its main interface method, which starts the job. For synchronous jobs, the execution environment calls com.sun.star.task.XJob:execute, whereas asynchronous jobs are run through com.sun.star.task.XAsyncJob:executeAsync.

Both methods take one parameter Arguments, which is a sequence of com.sun.star.beans.NamedValue structs. This sequence describes the job context.

It contains the environment where the job is running, which tells if the job was called by the job executor, the dispatch framework or the global event broadcaster service, and possibly provides a frame or a document model for the job to work with.

The Arguments parameter also yields configuration data, if the job has been configured in the configuration branch org.openoffice.Office.Jobs. This data is separated into basic configuration and additional arguments stored in the configuration. The job configuration is described in section Configuration.

Finally, Arguments can contain dynamic parameters given to the job at runtime. For instance, if a job has been called by the dispatch framework, and the dispatched command URL used parameters, these parameters can be passed on to the job through the execution arguments.

The following table shows the exact specification for the execution :

The following example shows how a job can analyze the given arguments and how the environment in which the job is executed can be detected:

Returning Results
Once a synchronous job has finished its work, it returns its result using the any return value of the com.sun.star.task.XJob:execute method. An asynchronous jobs send back the result through the callback method  to its com.sun.star.task.XJobListener. The returned any parameter must contain a  with the following elements:

Configuration
Although jobs that are called through a vnd.sun.star.jobs: URL by their implementation name do not require it, a job usually has configuration data. The configuration package org.openoffice.Office.Jobs contains all necessary information:

The Job template contains all properties that describe a job component. Instances of this template are located inside the configuration set Jobs.

The job property  was created to provide you with more flexibility for a developing components. You can use the same UNO implementation, but register it with different Aliases. At runtime the job instance will be initialized with its own configuration data and can detect which representation is used.

Every job instance can be bound to multiple events. An event indicates a special office state, which can be detected at runtime (for example,  ), and which can be triggered by a call to the job executor when the first document window is displayed.

As an optional feature, every job registration that is bound to an event can be enabled or disabled by two time stamp values. In a shared installation of LibreOffice, an administrator can use the  value to reactivate jobs for every newly started user office instance; regardless of earlier executions of these jobs. That can be useful, for example, for updating user installations if new functions have been added to the shared installation.

Using this time stamp feature can sometimes be complicated. For example, assume that there is a job that was installed using the Extension Manager. The job is enabled for a registered event by default, but after the first execution it is disabled. By default, both values ( and  ) do not exist for a configured event. A Jobs.xcu fragment, as part of the extension, must also not contain the  and   entries. Because both values are not there, no check can be made and the job is enabled. A job can be deactivated by the global job executor once it has finished its work successfully (depending on the  return value). In that case, the  entry is generated and set to the current time. An administrator can set a newer and valid  value in order to reactivate the job again, or the user can remove his   entry manually from the configuration file of the user installation.

The following Jobs.xcu file shows an example job configuration:

This example job has the following characteristics:


 * Its alias name is " "
 * The UNO implementation name of the component is.
 * The job has its own set of configuration data with one item. It is a string, its name is  and its value is " ".
 * The job is bound to the global event, which is triggered when the first document window of a new LibreOffice instance is displayed. The next execution of this job is guaranteed, because there are no time stamp values present.

When specifying the event to which the job is bound ( in the above example), it is important to use , so that multiple Jobs.xcu particles merge losslessly. but note that  is only available since OpenOffice.org 2.0.3, and that a Jobs.xcu file that uses it cannot be used with older versions of OpenOffice.org. With older versions of OpenOffice.org, it was common to use  instead of , which potentially caused event bindings to get lost when multiple Jobs.xcu particles were merged.

Installation
The easiest way to register an external job component is to use the Extension Manager (see chapter Extensions). An extension for the example job of this chapter can have the following directory structure:

SyncJob.oxt: META-INF/manifest.xml Jobs.xcu windows.plt/ SyncJob.jar

Using the vnd.sun.star.jobs: URL Schema
This section describes the necessary steps to execute a job by issuing a command URL at the dispatch framework. Based upon the protocol handler mechanism, a specialized URL schema has been implemented in LibreOffice. It is registered for the URL schema " " which uses the following syntax:

vnd.sun.star.job:{[event=&lt;name&gt;]}{,[alias=&lt;name&gt;]}{,[service=&lt;name&gt;]}

It is possible to combine elements so as to start several jobs at once with a single URL. For instance, you could dispatch a URL vnd.sun.star.job:event=e1,alias=a1,event=e2,…. However, URLs that start several jobs at once should be used carefully, since there is no check for double or concurrent requests. If a service is designed asynchronously, it will be run concurrently with another, synchronous job. If both services work at the same area, there might be race conditions and they must synchronize their work. The generic job execution mechanism does not provide this functionality.

The following configuration file for the configuration package org.openoffice.Office.Jobs shows two jobs, which are registered for different events:

The first job can be described by the following properties:

The second job can be described by these properties:

The following demonstrates use cases for all possible vnd.sun.star.job: URLs. Not all possible scenarios are shown here. The job dispatch can be used in different ways and the combination of jobs can produce different results:

vnd.sun.star.job:event=onFirstVisibleTask

This URL starts  only,   is marked , since its   stamp is older than its   stamp.

The job is initialized with environment information through the Environment sub list, as shown in section Initialization. Optional dispatch arguments are passed in, and generic configuration data, including the event string, is received in. However, it is not initialized with configuration data of its own in  because   is not configured with such information. On the other hand,  may return data after finishing its work, which will be written back to the configuration.

Furthermore, the job instance can expect that the  property from the   sub list points to the frame in which the dispatch request is to be executed.

vnd.sun.star.job:alias=Job_1

This starts  only. It is initialized with an environment, and optionally initialized with dispatch arguments, generic configuration data, and configuration data of its own. However, the event name is not set here because this job was triggered directly, not using an event name.

vnd.sun.star.job:service=vnd.sun.star.jobs.Job_3

A  is not registered in the job configuration package. However, if this implementation was registered with the global service manager, and if it provided the com.sun.star.task.XJob or com.sun.star.task.XAsyncJob interfaces, it would be executed by this URL. If both interfaces are present, the synchronous version is preferred.

The given UNO implementation name  is used directly for creation at the UNO service manager. In addition, this job instance is only initialized with an environment and possibly with optional dispatch arguments - there is no configuration data for the job to use.

Add-Ons
An LibreOffice add-on is an extension providing one or more functions through the user interface of LibreOffice. A typical add-on is available as an extension for easier deployment with the Extension Manager. An add-on contains configuration files which specify the user interface, registration for a protocol schema and first-time instantiation.

The Extension Manager merges the configuration files with the menu and toolbar items for an add-on directly into the LibreOffice configuration files.

Overview
LibreOffice supports the integration of add-ons into the following areas of the GUI.

Menu items for add-ons can be added to an Add-Ons submenu of the Tools menu and a corresponding add-ons popup toolbar icon:



It is also possible to create custom menus in the Menu Bar. You are free to choose your own menu title, and you can create menu items and submenus for your add-on. Custom menus are inserted between the Tools and Window menus. Separators are supported as well:



You can create toolbar icons in the Function Bar, which is usually the topmost toolbar. Below you see two toolbar items, an icon for Function 1 and a text item for Function 2.



The Help menu offers support for add-ons through help menu items that open the online help of an add-on. They are inserted below the Help - Registration item under a separator.

Guidelines
For a smooth integration, a developer should be aware of the following guidelines:

Add-Ons Submenu

 * Since the Tools - Add-Ons menu is shared by all installed add-ons, an add-on should save space and use a submenu when it has more than two functions. The name of the add-on should be part of the menu item names or the submenu title.
 * If your add-on has many menu items, use additional submenus to enhance the overview. Use four to seven entries for a single menu. If you exceed this limit, start creating submenus.

Custom Top-Level Menu

 * Only frequently used add-ons or add-ons that offer very important functions in a user environment should use their own top-level menu.
 * Use submenus to enhance the overview. Use four to seven entries for a single menu. If you exceed this limit, start creating submenus.
 * Use the option to group related items by means of separator items.

Before version 2.0.3 of OpenOffice.org

 * Only important functions should be integrated into the toolbar.
 * Use the option to group functions by means of separator items.

Since version 2.0.3 of OpenOffice.org

 * Each extension may have its own toolbar. The toolbar may have a specific title.

Menu Bar and Tool Bar merging
Since version 2.3 of OpenOffice.org an extension may integrate commands into an existing menu or toolbar. See Wiki article Addon Menu Toolbar Merging.

Before version 2.4 of OpenOffice.org
Every add-on should provide help to user. This help has to be made available through an entry in the LibreOffice Help menu. Every add-on should only use a single Help menu item.

If the add-on comes with its own dialogs, it should also offer Help buttons in the dialogs.

Since version 2.4 of OpenOffice.org
Extensions can contain help content and extend the LibreOffice's installed help content. Add-on Help is now legacy. See instead chapter Help Content.

Configuration
The user interface definitions of all add-ons are stored in the special configuration branch org.openoffice.Office.Addons.

The schema of the configuration branch org.openoffice.Office.Addons specifies how to define a user interface extension.

Menus
As explained in the previous section, LibreOffice supports two menu locations where an add-on can be integrated: a top-level menu or the Tools - Add-Ons submenu. The configuration branch org.openoffice.Office.Addons provides two different nodes for these locations:

Submenu in
To integrate add-on menu items into the menu, use the   set. The  set consists of nodes of type. The  node-type is also used for the submenus of a top-level add-on menu.

The next examples shows a configuration file specifying a single menu item titled Add-On Function 1. The unique node name of the add-on is called org.openoffice.example.addon.example.function1.

Top-level Menu
If you want to integrate an add-on into the LibreOffice Menu Bar, you have to use the  set. An  set consists of nodes of type.

The following example defines a top-level menu titled Add-On example with a single menu item titled Add-On Function 1. The menu item has a self-defined image used for displaying it next to the menu title.In the example the nodes are called " and.

Do not forget to specify the  attribute in your self-defined nodes. The replace operation must be used to add a new node to a set or extensible node. Thus the real meaning of the operation is "add or replace". Dynamic properties can only be added once and are then considered mandatory, so during layer merging the replace operation always means "add" for them.For more details about the configuration and their file formats please read Configuration Management.

Toolbars
Add-on toolbar, before version 2.0.3 of OpenOffice.org


 * An add-on can also be integrated into the Function Bar of LibreOffice. The org.openoffice.Office.Addons configuration branch has a set called  where you can add toolbar items for an add-on. The toolbar structure uses an embedded set called , which is used by LibreOffice to group toolbar items from different add-ons. LibreOffice automatically inserts a separator between different add-ons toolbar items.
 * The space of the Function Bar is limited, so only the most used/important functions should be added to the OfficeToolBar set. Otherwise LibreOffice will add scroll-up/down buttons at the end of the Function Bar and the user has to scroll the toolbar to have access to all toolbar buttons.

Extension toolbar, since version 2.0.3 of OpenOffice.org


 * Each extension may have its own toolbar. The toolbar may have a specific title.

The  set is a container for the   nodes.

The following example defines one toolbar button for the function called. The toolbar button is only visible when using the LibreOffice Writer module.

Toolbar title
Since version 2.0.3 of OpenOffice.org an extension toolbar may have a specific title.

The framework based layout manager uses a modified resource URL schema to address add-on toolbars:
 * private:resource/toolbar/addon_<name of the toolbar set node>

As the new schema uses a unique name which is known at installation time, the toolbar name can be associated to this resource URL.

In the above example of Addons.xcu file defining a toolbar, the name of the toolbar set node is org.openoffice.Office.addon.example. Therefore the resource URL will be
 * private:resource/toolbar/addon_org.openoffice.Office.addon.example

An extension can define the toolbar title with <Module>WindowState.xcu files. The title of the toolbar must be set for each module where the toolbar will appear. One such file is necessary for each module. Continuing the example, the toolbar title for Writer module will be specified in a WriterWindowState.xcu file:

The UIName property supports localization.

Each <Module>WindowState.xcu file must be declared as a configuration data file in the manifest.xml file.

Images for Toolbars and Menus
LibreOffice supports images in menus and toolboxes. In addition to the property, the add-ons configuration branch has a fourth set called   that let developers define and use their own images. The image data can be integrated into the configuration either as hex encoded binary data or as references to external bitmap files. The  set binds a command URL to user defined images.

An  node uses a second node called   where the user defined images data are stored.

The embedded image data have a higher priority when used in conjunction with the URL properties. The embedded and URL properties can be mixed without a problem.

The next example creates two user-defined images for the function. The normal image is defined using the embedded image data property ImageSmall and has a size of 16x16 pixel and a 4-bit color depth. The other one uses the URL property ImageSmallHCURL to reference an external bitmap file for the high contrast image. Referencing an external png image would be same, only the extension changes.

Help Integration
LibreOffice supports the integration of add-ons into its Help menu. The add-on help menu items are inserted below the Registration menu item, guarded by separators. This guarantees that users have quick access to the add-on help. The OfficeHelp set uses the same MenuItem node-type as the AddonMenu set, but there are some special treatments of the properties.

The following example shows the single help menu item for the add-on example.

Installation
After finishing the implementation of the UNO component and the definition of the user interface part you can create an extension. An extension can be used by an end-user to install the add-on into LibreOffice.

The configuration files that were created for the add-on, such as protocol handler, jobs, and user interface definition must be added to the root of the zip file. The structure of a zip file supporting Windows should resemble the following code:

example_addon.oxt: META_INF/ manifest.xml Addons.xcu ProtocolHandler.xcu windows.plt/ example_addon.dll

Before you install the extension, make absolutely sure there are no running instances of LibreOffice. The unopkgtool recognizes a running LibreOffice in a local installation, but not in a networked installation. Installing into a running office installation might cause inconsistencies and destroy your installation!

The extension installation for the example add-on is as simple as changing to the <OfficePath>/program directory with a command-line shell and running

[<OfficePath>/program] $ unopkg add /foo/bar/example_addon.zip

For an explanation of other deployment options, please refer to Deployment Options for Components and for an explanation about extensions refer to Extensions.

Disable Commands
In LibreOffice, there may be situations where functions should be disabled to prevent users from changing or destroying documents inadvertently. LibreOffice maintains a list of disabled commands that can be maintained by users and developers through the configuration API.

A command request can be created by any object, but in most cases, user interface objects create these requests. Consider, for instance, a toolbox where different functions acting on the office component are presented as buttons. Once a button is clicked, the desired functionality should be executed. If the code assigned to the button is provided with a suitable command URL, the dispatch framework can handle the user action by creating the request and finding a component that can handle it.

The dispatch framework works with the design pattern chain of responsibility: everything a component needs to know if it wants to execute a request is the last link in a chain of objects capable of executing requests. If this object gets the request, it checks whether it can handle it or otherwise passes it to the next chain member until the request is executed or the end of the chain is reached. The disable commands implementation is the first chain member and can therefore work as a wall for all disabled commands. They are not be sent to the next chain member, and disappear.

The illustration below shows how the disable commands feature affects the normal command application flow.



Configuration
The disable commands feature uses the configuration branch org.openoffice.Office.Commands to read which commands should be disabled. The following schema applies:

The configuration schema for disabled commands is very simple. The org.openoffice.Office.Commands branch has a group called. This group has only one set called. The  set supports nodes of the type. The following table describes the supported properties of.

The example below shows a configuration file that disables the commands for File – Open, Edit – Select All, Help – About LibreOffice and File – Exit.

A few lines on the node name 'com.mycompany.a-chosen-unique-name.m1' in the xml example above.

The node name is chosen in order to be unique in the 'Disable' data set, and is given as a suggestion.

You can use whatever name you like, it has no additional meaning for the implementation of the disable commands feature.

A good idea would be to use a consecutive numbering at the name end, the name must be unique.

Disabling Commands at Runtime
The following code example first removes all commands that were defined in the user layer of the configuration branch  as having a defined starting point. Then it checks if it can get dispatch objects for some pre-defined commands.Then the example disables these commands and tries to get dispatch objects for them again. At the end, the code removes the disabled commands again, otherwise LibreOffice would not be fully usable any longer.

Intercepting Context Menus
A context menu is displayed when an object is right clicked. Typically, a context menu has context dependent functions to manipulate the selected object, such as cut, copy and paste. Developers can intercept context menus before they are displayed to cancel the execution of a context menu, add, delete, or modify the menu by replacing context menu entries or complete sub menus. It is possible to provide new customized context menus.

Context menu interception is implemented by the observer pattern. This pattern defines a one-to-many dependency between objects, so that when an object changes state, all its dependents are notified. The implementation supports more than one interceptor. The root access point for intercepting context menus is a com.sun.star.frame.Controller object. The controller implements the interface com.sun.star.ui.XContextMenuInterception to support context menu interception.

Register and Remove an Interceptor
The com.sun.star.ui.XContextMenuInterception interface enables the developer to register and remove the interceptor code. When an interceptor is registered, it is notified whenever a context menu is about to be executed. Registering an interceptor adds it to the front of the interceptor chain, so that it is called first. The order of removals is arbitrary. It is not necessary to remove the interceptor that registered last.

Notification
A context menu interceptor implements the com.sun.star.ui.XContextMenuInterceptor interface. This interface has one function that is called by the responsible controller whenever a context menu is about to be executed.

The com.sun.star.ui.ContextMenuExecuteEvent is a struct that holds all the important information for an interceptor.

Querying a Menu Structure
The ActionTriggerContainer member is an indexed container of context menu entries, where each menu entry is a property set. It implements the com.sun.star.ui.ActionTriggerContainer service. The interface com.sun.star.container.XIndexContainer directly accesses the intercepted context menu structure through methods to access, insert, remove and replace menu entries.

All elements in an  member support the com.sun.star.beans.XPropertySet interface to get and set property values. There are two different types of menu entries with different sets of properties:

It is essential to determine the type of each menu entry be querying it for the interface com.sun.star.lang.XServiceInfo and calling

The following example shows a small helper class to determine the correct menu entry type.

Figure 4.1: Determine the menu element type

The com.sun.star.ui.ActionTrigger service supported by selectable menu entries has the following properties:

The com.sun.star.ui.ActionTriggerSeparator service defines only one optional property:

Changing a Menu
It is possible to accomplish certain tasks without implementing code in a context menu interceptor, such as preventing a context menu from being activated. Normally, a context menu is changed to provide additional functions to the user.

As previously discussed, the context menu structure is queried through the ActionTriggerContainer member that is part of the com.sun.star.ui.ContextMenuExecuteEvent structure. The com.sun.star.ui.ActionTriggerContainer service has an additional interface com.sun.star.lang.XMultiServiceFactory that creates [IDL:com.sun.star.ui.ActionTriggerContainer], com.sun.star.ui.ActionTriggerContainer and com.sun.star.ui.ActionTriggerSeparator objects. These objects are used to extend a context menu.

The com.sun.star.lang.XMultiServiceFactory implementation of the ActionTriggerContainer implementation supports the following strings:

1 A sub menu cannot exist by itself. It has to be inserted into a com.sun.star.ui.ActionTrigger !

2 The separator has no special type. It is the responsibility of the concrete implementation to render an unspecified separator.

Finishing Interception
Every interceptor that is called directs the controller how it continues after the call returns. The enumeration com.sun.star.ui.ContextMenuInterceptorAction defines the possible return values.

The following example shows a context menu interceptor that adds a a sub menu to a menu that has been intercepted at a controller, where this com.sun.star.ui.XContextMenuInterceptor has been registered. This sub menu is inserted into the context menu at the topmost position. It provides help functions to the user that are reachable through the menu Help.

File Naming Conventions
As a recommendation, UNO component libraries should be named according to the following naming scheme:

<NAME>[<VERSION>].uno.(so|dll|dylib|jar)

This recommendation applies to shared libraries and Java archives,which are deployed by the Extension Manager as described in section Extensions.

This file name convention results in file names such as:


 * component.uno.so
 * component1.uno.dll
 * component0.1.3.uno.dylib
 * component.uno.jar

<NAME> should be a descriptive name, optionally extended by version information as shown below, followed by the characters .uno and the necessary file extension.

The term .uno is placed next to the platform-specific extension to emphasize that this is a special type of shared library, jar, or zip file.

Usually a shared library or jar has to be registered with UNO to be useful, as its shared library interface only consists of the component operations.

Since the given naming scheme is only a suggestion, there might be component shared libraries that do not contain the .uno addition in their names. Therefore, no tool should build assumptions on whether a shared library name contains .uno or not.

<VERSION> is optional and should be in the form:

<VERSION> = <MAJOR> [.<MINOR> [.<MICRO>]] <MAJOR>  = <NUMBER> <MINOR>  = <NUMBER> <MICRO>  = <NUMBER> <NUMBER> = 0 | 1–9 0–9*

Using the version tag in the file name of a shared library or jar is primarily meant for simple components that are not part of an extension deployed by the Extension Manager. Such components are usually made up of a single shared library, and different file names for different versions can be useful, for instance in bug reports.

The version of components that are part of the LibreOffice installation is already well-defined by the version and build number of the installed LibreOffice itself.

It is up to the developer how the version scheme is used. You can count versions of a given component shared library using MAJOR alone, or add MINOR and MICRO as needed.

The following considerations give an overview of ways that a component can evolve:

A component shared library's interface, as defined by the component operations such as  is assumed to be stable.

The UNO services offered by a component can change:


 * compatibly : by changing an implementation in the component file but adhering to its specification, or by adding a new UNO service implementation to a component file
 * incompatibly: by removing an implementation, or by removing a UNO service from a component
 * indirectly compatibly: when one of the UNO services changes compatibility and the component is adapted accordingly. This can happen when a service specification is extended by additional optional interfaces, and the component is altered to support these interfaces.

When an implementation in a component file is changed, for instance when a bug is fixed, such a change will typically be compatible unless clients made themselves dependent on the bug. This can happen when clients considered the bug a feature or worked around the bug in a way that made them dependent on the bug. Therefore developers must be careful to program according to the specification, not the implementation.

Finally, a component shared library can change its dependencies on other shared libraries. Examples of such dependencies are:

C/C++ runtime libraries
 * such as libc.so.6, libstdc++.so.3.0.1, and libstlport_gcc.so

UNO runtime libraries
 * such as libcppu.so.3.1.0 and libcppuhelpergcc3.so.3.1.0

[PRODUCTNAME] libraries
 * such as libsvx644li.so

Dependency changes are typically incompatible, as they rely on compatible or incompatible changes of the component's environment.

Deployment Options for Components
Component are usually distributed and deployed as extensions (see chapter Extensions). However, by using legacy tools, such as regcomp, and regmerge, it is also possible to install components, which can be more convenient during development.

Background: UNO Registries
This section explains the necessary steps to deploy new UNO components manually into an installed LibreOffice. Background information is provided and the tools required to test deployment are described. The developer and deployer of the component should be familiar with this section. If the recommendations provided are accepted, interoperability of components of different vendors can be achieved easily.

UNO registries store binary data in a tree-like structure. The stored data can be accessed within a registry programmatically through the com.sun.star.registry.SimpleRegistry service, however this is generally not necessary. Note that UNO registries have nothing to do with the Windows registry, except that they follow a similar concept for data storage.

UNO-registries mainly store two types of data :

Type-library
 * To invoke UNO calls from BASIC or through an interprocess connection, the core UNO bridges need information about the used data types. UNO stores this information into a type library, so that the same data is reusable from any bridge. This is in contrast to the CORBA approach, where code is generated for each data type that needs to be compiled and linked into huge libraries. Every UNOIDL type description is stored as a binary large object (BLOB) that is interpreted by the com.sun.star.reflection.TypeDescriptionProvider service.

Information about registered components
 * One basic concept of UNO is to create an instance of a component simply by its service name through the . The association between the service name and the shared library or .jar-file where the necessary compiled code is found is stored into a UNO-registry.
 * The structure of this data is provided below. Future versions of LibreOffice will probably store this information in an XML file that will make it modifiable using a simple text editor.

Both types of data are necessary to run a UNO-C++ process. If the types of data are not present, it could lead to termination of the program. UNO processes in general open their registries during startup and close them when the process terminates. Both types of data are commonly stored in a file with an .rdb suffix ( rdb=registry database ), but this suffix is not mandatory.

UNO Type Library
All type descriptions must be available within the registry under the /UCR main key (UCR = Uno Core Reflection) to be usable in a UNO C++ process. Use the regview tool to view the file  /program/types.rdb. The regview tool comes with the LibreOffice SDK.

For instance:

$ regview types.rdb /UCR

prints all type descriptions used within the office to. To check if a certain type is included within the registry, invoke the following command:

$ regview types.rdb /UCR/com/sun/star/bridge/XUnoUrlResolver

/UCR/com/sun/star/bridge/XUnoUrlResolver Value: Type = RG_VALUETYPE_BINARY Size = 461 Data = minor version: 0 major version: 1 type: 'interface' name: 'com/sun/star/bridge/XUnoUrlResolver' super name: 'com/sun/star/uno/XInterface' Doku: "" number of fields: 0 number of methods: 1 method #0: com/sun/star/uno/XInterface resolve([in] string sUnoUrl) raises com/sun/star/connection/NoConnectException, com/sun/star/connection/ConnectionSetupException, com/sun/star/lang/IllegalArgumentException Doku: "" number of references: 0

The regview tool decodes the format of the BLOB containing the type description and presents it in a readable form.

Component Registration
The UNO component provides the data about what services are implemented. In order not to load all available UNO components into memory when starting a UNO process, the data is assembled once during setup and stored into the registry. The process of writing this information into a registry is called component registration. The tools used to perform this task are discussed below.

For an installed LibreOffice, the services.rdb contains the component registration information. The data is stored within the /IMPLEMENTATIONS and /SERVICES key. The code below shows a sample SERVICES key for the com.sun.star.io.Pipe service.

The code above contains one implementation name, but it could contain more than one. In this case, only the first is used. The following entry can be found within the  section:

The implementations section holds three types of data.


 * 1) The loader to be used when the component is requested at runtime (here com.sun.star.loader.SharedLibrary ).
 * 2) The services supported by this implementation.
 * 3) The URL to the file the loader uses to access the library (the url may be given relative to the LibreOffice library directory for native components as it is in this case).

Command Line Registry Tools
There are various tools to create, modify and use registries. This section shows some common use cases. The regmerge tool is used to merge multiple registries into a sub-key of an existing or new registry. For instance:

$ regmerge new.rdb / test1.rdb test2.rdb

merges the contents of test1.rdb and test2.rdb under the root key / of the registry database new.rdb. The names of the keys are preserved, because both registries are merged into the root-key. In case new.rdb existed before, the previous contents remain in new.rdb unless an identical key names exist in test1.rdb and test2.rdb. In this case, the content of these keys is overwritten with the ones in test1.rdb or test2.rdb. So the above command is semantically identical to:

$ regmerge new.rdb / test1.rdb $ regmerge new.rdb / test2.rdb

The following command merges the contents of test1.urd and test2.urd under the key /UCR into the file myapp_types.rdb.

$ regmerge myapp_types.rdb /UCR test1.urd test2.urd

The names of the keys in test1.urd and test2.urd should only be added to the /UCR key. This is a real life scenario as the files produced by the idl-compiler have a .urd-suffix. The regmerge tool needs to be run before the type library can be used in a program, because UNO expects each type description below the /UCR key.

Component Registration Tool
Components can be registered using the regcomp tool. Below, the components necessary to establish an interprocess connection are registered into the myapp_services.rdb.

$ regcomp -register -r myapp_services.rdb \ -c uuresolver.dll \ -c brdgfctr.dll \ -c acceptor.dll \ -c connectr.dll \ -c remotebridge.dll

The \ means command line continuation. The option -r gives the registry file where the information is written to. If it does not exist, it is created, otherwise the new data is added. In case there are older keys, they are overwritten. The registry file (here myapp_services.rdb) must NOT be opened by any other process at the same time. The option -c is followed by a single name of a library that is registered. The -c option can be given multiple times. The shared libraries registered in the example above are needed to use the UNO interprocess bridge.

Registering a Java component is currently more complex. It works only in an installed office environment, the <OfficePath>/program must be the current working directory, the office setup must point to a valid Java installation that can be verified using jvmsetup from <OfficePath>/program, and Java must be enabled. See Tools - Options - General - Security. In OpenOffice.org 2.x, make sure that a Java is selected by using the Java panel of the options dialog (Tools - Options - OpenOffice - Java).

The office must not run. On Unix, the LD_LIBRARY_PATH environment variable must additionally contain the directories listed by the javaldx tool (which is installed with the office).

Copy the regcomp executable into the  /program directory. The regcomp tool must then be invoked using the following parameters :

$ regcomp -register -r your_registry.rdb \ -br /program/services.rdb \ -l com.sun.star.loader.Java2 \ -c file:///d:/test/JavaTestComponent.jar

The option -r (registry) tells regcomp where to write the registration data and the -br (bootstrap registry) option points regcomp to a registry to read common types from. The regcomp tool does not know the library that has the Java loader. The -l option gives the service name of the loader to use for the component that must be. The option can be omitted for C++ components, because regcomp defaults to the com.sun.star.loader.SharedLibrary loader. The option -c gives the file url to the Java component.

File urls can be given absolute or relative. Absolute file urls must begin with file:///. All other strings are interpreted as relative file urls. The 3rdpartYcomp/filterxy.dll, ../../3rdpartycomp/filterxyz.dll, and filterxyz.dll are a few examples. Relative file urls are interpreted relative to all paths given in the PATH variable on Windows and LD_LIBRARY_PATH variable on Unix.

Java components require an absolute file URL for historical reasons.

UNO Type Library Tools
There are several tools that currently access the type library directly. They are encountered when new UNOIDL types are introduced.


 * idlc, Compiles .idl files into .urd-registry-files.
 * cppumaker, Generates C++ header for a given UNO type list from a type registry used with the UNO C++ binding.
 * javamaker, Generates Java .class files for a given type list from a type registry.
 * rdbmaker, Creates a new registry by extracting given types (including dependent types) from another registry, and is used for generating minimal, but complete type libraries for components. It is useful when building minimal applications that use UNO components.
 * regmerge, Merges multiple registries into a certain sub-key of a new or already existing registry.

Manually Merging a Registry and Adding it to uno.ini or soffice.ini
Registry files used by LibreOffice are configured within the uno(.ini|rc) file found in the program directory. After a default LibreOffice installation, the files look like this:

uno.ini : [Bootstrap] UNO_TYPES=$ORIGIN/types.rdb UNO_SERVICES=$ORIGIN/services.rdb

The two UNO variables are relevant for UNO components. The UNO_TYPES variable gives a space separated list of type library registries, and the UNO_SERVICES variable gives a space separated list of registries that contain component registration information. These registries are opened read-only. The same registry may appear in UNO_TYPES and UNO_SERVICES variables. The $ORIGIN points to the directory where the ini/rc file is located.

LibreOffice uses the types.rdb as a type and the services.rdb as a component registration information repository. When a programmer or software vendor releases a UNO component, the following files must be provided at a minimum:


 * A file containing the code of the new component, for instance a shared library, a jar file, or maybe a python file in the future.
 * A registry file containing user defined UNOIDL types, if any.
 * (optional) A registry file containing registration information of a pre-registered component. The registry provider should register the component with a relative path to be beneficial in other LibreOffice installations.

The latter two can be integrated into a single file.

The recommended method to add a component to LibreOffice manually is described in the following steps:


 * 1) Copy new shared library components into the <OfficePath>/program directory and new Java components into the <OfficePath>/program/classes directory.
 * 2) Copy the registry containing the type library into the <OfficePath>/program directory, if needed and available.
 * 3) Copy the registry containing the component registration information into the <OfficePath>/program directory, if required. Otherwise, register the component with the regcomp command line tool coming with the LibreOffice SDK into a new registry.
 * 4) Modify the uno(.ini|rc) file, and add the type registry to the UNO_TYPES variable and the component registry to the UNO_SERVICES variable. The new uno(.ini|rc) might look like this:

[Bootstrap] UNO_TYPES=$ORIGIN/types.rdb $ORIGIN/filterxyz_types.rdb UNO_SERVICES=$ORIGIN/services.rdb $ORIGIN/filterxyz_services.rdb

After these changes are made, every office that is restarted can use the new component. The uno(.ini|rc) changes directly affect the whole office network installation. If adding a component only for a single user, pass the modified UNO_TYPES and UNO_SERVICES variables per command line. An example might be:

$ soffice “-env:UNO_TYPES=$ORIGIN/types.rdb $ORIGIN/filterxyz_types.rdb“ “-env:UNO_SERVICES=$ORIGIN/services.rdb $ORIGIN/filter_xyz_services.rdb” ).

Bootstrapping a Service Manager
Bootstrapping a service manager means to create an instance of a service manager that is able to instantiate the UNO objects needed by a user. All UNO applications, that want to use the UnoUrlResolver for connections to the office, have to bootstrap a local service manager in order to create a UnoUrlResolver object. If developers create a new language binding, for instance for a scripting engine, they have to find a way to bootstrap a service manager in the target environment.

There are many methods to bootstrap a UNO C++ application, each requiring one or more registry files to be prepared. Once the registries are prepared, there are different options available to bootstrap your application. A flexible approach is to use UNO bootstrap parameters and the  function.

No arguments, such as a registry name, are passed to this function. These are given using bootstrap parameters. Bootstrap parameters can be passed through a command line, an .ini file or using environment variables.

For bootstrapping the UNO component context, the following two variables are relevant:

An absolute file URL must begin with the file:/// prefix (on Windows, it must look like file:///c:/mytestregistry.rdb). To make a file URL relative, the file:/// prefix must be omitted. The relative url is interpreted relative to the current working directory.
 * 1) UNO_TYPES: Gives a space separated list of type library registry files. Each registry must be given as an absolute or relative file url. Note that some special characters within the path require encoding, for example, a space must become a %20. The registries are opened in read-only.
 * 2) UNO_SERVICES: Gives a space separated list of registry files with component registration information. The registries are opened in read-only. The same registry may appear in UNO_TYPES and UNO_SERVICES variables.

Within the paths, use special placeholders.

The advantage of this method is that the executable can be configured after it has been built. The LibreOffice bootstraps the service manager with this mechanism.

Consider the following example:

A tool needs to be written that converts documents between different formats. This is achieved by connecting to LibreOffice and doing the necessary conversions. The tool is named docconv. In the code, the  function is used as described above to create the component context. Two registries are prepared: docconv_services.rdb with the registered components and types.rdb that contains the types coming with LibreOffice. Both files are placed beside the executable. The easiest method to configure the application is to create a docconv(.ini|rc) ascii file in the same folder as your executable, that contains the following two lines:

UNO_TYPES=$ORIGIN/types.rdb UNO_SERVICES=$ORIGIN/docconv_services.rdb

No matter where the application is started form, it will always use the mentioned registries. Note that this also works on different machines when the volume is mapped to different location mount points as $SYSBINDIR is evaluated at runtime.

The second possibility is to set UNO_TYPES and UNO_SERVICES as environment variables, but this method has drawbacks. All UNO applications started with this shell use the same registries.

The third possibility is to pass the variables as command line parameters, for instance

docconv -env:UNO_TYPES=$ORIGIN/types.rdb -env: UNO_SERVICES=$ORIGIN/docconv_services.rdb

Note that on UNIX shells, you need to quote the $ with a backslash \.

The command line arguments do not need to be passed to the UNO runtime, because it is generally retrieved from some static variables. How this is done depends on the operating system, but it is hidden from the programmer. The docconv executable should ignore all command line parameters beginning with '-env:'. The easiest way to do this is to ignore  and   and to use the   functions defined in rtl/process.h header instead which automatically strips the additional parameters.


 * 1) Combine the methods mentioned above. Command line parameters take precedence over .ini file variables and .ini file parameter take precedence over environment variables. That way, it is possible to overwrite the UNO_SERVICES variable on the command line for one invocation of the program only.

Special Service Manager Configurations
The com.sun.star.container.XSet interface allows the insertion or removal of com.sun.star.lang.XSingleServiceFactory or com.sun.star.lang.XSingleComponentFactory implementations into or from the service manager at runtime without making these changes persistent. When the office applications terminate, all the changes are lost. The inserted object must support the com.sun.star.lang.XServiceInfo interface. This interface returns the same information as the XServiceInfo interface of the component implementation which is created by the component factory.

With this feature, a running office can be connected, a new factory inserted into the service manager and the new service instantiated without registering it beforehand. This method of hard coding the registered services is not acceptable with LibreOffice, because it must be extended after compilation.

Java applications can use a native persistent service manager in their own process using JNI (see Java Language Binding), or in a remote process. But note, that all services will be instantiated in this remote process.

Dynamically Modifying the Service Manager
Bootstrapping in pure Java is simple, by calling the static runtime method  from the Bootstrap class. The following small test program shows how to insert service factories into the service manager at runtime. The sample uses the Java component from the section Simple Component in Java. The complete code can be found with the JavaComp sample component.

The example shows that there is the possibility to control through command line parameter, whether the service is inserted in the local Java service manager or the remote office service manager. If it is inserted into the office service manager, access the service through LibreOffice Basic. In both cases, the component runs in the local Java process.

If the service is inserted into the office service manager, instantiate the component through LibreOffice Basic calling, as long as the Java process is not terminated. Note, to add the new types to the office process by one of the above explained mechanisms, use uno.ini.

Creating a ServiceManager from a Given Registry File
To create a service manager from a given registry, use a single registry that contains the type library and component registration information. Hard code the name of the registry in the program and use the  function located in the cppuhelper library.

The UNO Executable
In chapter C++ Language Binding, several methods to bootstrap a UNO application were introduced. In this section, the option UNO executable is discussed. With UNO executable, there is no need to write executables anymore, instead only components are developed. Code within executables is locked up, it can only run by starting the executable, and it can never be used in another context. Components offer the advantage that they can be used from anywhere. They can be executed from Java or from a remote process.

For these cases, the com.sun.star.lang.XMain interface was introduced. It has one method:

Instead of writing an executable, write a component and implement this interface. The component gets the fully initialized service manager during instantiation. The  method then should do what a   function would have done. The UNO executable offers one possible infrastructure for using such components.

Basically, the uno tool can do two different things:


 * 1) Instantiate a UNO component which supports the [IDL:com.sun.star.lang.XMain] interface and executes the   method.

<li>Export a UNO component to another process by accepting on a resource, such as a tcp/ip socket or named pipe, and instantiating it on demand.</li> </ol>

In both cases, the uno executable creates a UNO component context which is handed to the instantiated component. The registries that should be used are given by command line arguments. The goal of this tool is to minimize the need to write executables and focus on writing components. The advantage for component implementations is that they do not care how the component context is bootstrapped. In the future there may be more ways to bootstrap the component context. While executables will have to be adapted to use the new features, a component supporting  can be reused.

Standalone Use Case
Simply typing uno gives the following usage screen :

uno (-c ComponentImplementationName -l LocationUrl | -s ServiceName) [-ro ReadOnlyRegistry1] [-ro ReadOnlyRegistry2] ... [-rw ReadWriteRegistry] [-u uno:(socket[,host=HostName][,port=nnn]|pipe[,name=PipeName]);urp;Name [--singleaccept] [--singleinstance]] [-- Argument1 Argument2 ...]

Choosing the implementation to be instantiated
 * Using the option -s servicename gives the name of the service which shall be instantiated. The uno executable then tries to instantiate a service by this name, using the registries as listed below.


 * Alternatively, the -l and -c options can be used. The -l gives an url to the location of the shared library or .jar file, and -c the name of the desired service implementation inside the component. Remember that a component may contain more than one implementation.

Choosing the registries for the component context (optional)
 * With the option -ro, give a file url to a registry file containing component's registration information and/or type libraries. The -ro option can be given multiple times. The -rw option can only be given once and must be the name of a registry with read/write access. It will be used when the instantiated component tries to register components at runtime. This option is rarely needed.


 * Note that the uno tool ignores bootstrap variables, such as UNO_TYPES and UNO_SERVICES.

The UNO URL (optional)
 * Giving a UNO URL causes the uno tool to start in server mode, then it accepts on the connection part of the UNO URL. In case another process connects to the resource (tcp/ip socket or named pipe), it establishes a UNO interprocess bridge on top of the connection (see also UNO Interprocess Connections). Note that urp should always be used as protocol. An instance of the component is instantiated when the client requests a named object using the name, which was given in the last part of the UNO URL.

Option 
 * Only meaningful when a UNO URL is given. It tells the uno executable to accept only one connection, thus blocking any further connection attempts.

Option 
 * Only meaningful when a UNO URL is given. It tells the uno executable to always return the same (first) instance of the component, thus multiple processes communicate to the same instance of the implementation. If the option is not given, every getInstance call at the com.sun.star.bridge.XBridge interface instantiates a new object.

Option  (double dash)
 * Everything following  is interpreted as an option for the component itself. The arguments are passed to the component through the   call of com.sun.star.lang.XInitialization interface.

The following example shows how to implement a Java component suitable for the uno executable.

The class itself inherits from com.sun.star.lang.XMain. It implements a constructor with the com.sun.star.uno.XComponentContext interface and stores the component context for future use. Within its  method, it prints 'Hello World'. The last two mandatory functions are responsible for instantiating the component and writing component information into a registry. Refer to Simple Component in Java for further information.

The code needs to be compiled and put into a .jar file with an appropriate manifest file:

RegistrationClassName: UnoExeMain

These commands create the jar:

javac UnoExeMain jar -cvfm UnoExeMain.jar Manifest UnoExeMain.class

To be able to use it, register it with the following command line into a separate registry file (here test.rdb). The <OfficePath>/program directory needs to be the current directory, and the regcomp and uno tools must have been copied into this directory.

regcomp -register \ -br /program/services.rdb \ -r test.rdb \ -c file:///c:/devmanual/Develop/samples/unoexe/UnoExeMain.jar \ -l com.sun.star.loader.Java2

The \ means command line continuation.

The component can now be run:

uno -s MyMain -ro types.rdb -ro services.rdb -ro test.rdb

This command should give the output "hello world !"

Server Use Case
This use case enables the export of any arbitrary UNO component as a remote server. As an example, the com.sun.star.io.Pipe service is used which is already implemented by a component coming with the office. It exports an com.sun.star.io.XOutputStream and a com.sun.star.io.XInputStream interface. The data is written through the output stream into the pipe and the same data from the input stream is read again. To export this component as a remote server, switch to the <OfficePath>/program directory and issue the following command line.

i:\o641l\program>uno -s com.sun.star.io.Pipe -ro types.rdb -ro services.rdb -u uno:socket,host=0,port=2002;urp;test

> accepting socket,host=0,port=2083...

Now a client program can connect to the server. A client may look like the following:

After bootstrapping the component context, the  service is instantiated to access remote objects. After resolving the remote object, check whether it really supports the Pipe service. For instance, try to connect this client to a running LibreOffice - this check will fail. A byte array with five elements is written to the remote server and read again with two  calls. Starting the client with the following command line connects to the server started above. You should get the following output:

I:\tmp>java UnoExeClient uno:socket,host=localhost,port=2083;urp;test Available bytes : 5 read 2:1,2 Available bytes : 3 read 3:3,4,5 Terminating client

Using the UNO Executable
The main benefit of using the uno tool as a replacement for writing executables is that the service manager initialization is separated from the task-solving code and the component can be reused. For example, to have multiple XMain implementations run in parallel in one process. There is more involved when writing a component compared to writing an executable. With the bootstrap variable mechanism there is a lot of freedom in bootstrapping the service manager (see chapter C++ Language Binding).

The uno tool is a good starting point when exporting a certain component as a remote server. However, when using the UNO technology later, the tool does have some disadvantages, such as multiple objects can not be exported or the component can only be initialized with command line arguments. If the uno tool becomes insufficient, the listening part in an executable will have to be re-implemented.

Accessing Dialogs
This chapter describes how UNO Components can interact with dialogs that have been created with the Dialog Editor integrated in the LibreOffice Basic IDE. Before OpenOffice.org 2.0.4 dialogs designed with this Dialog Editor could only be reasonably used in the context of LibreOffice Basic respectively in the scope of the Scripting Framework (see Scripting Framework ). The reason for this restriction was the fact that only scripts managed by the Scripting Framework could be assigned as action to control events. It was already possible to instantiate dialogs using the com.sun.star.awt.XDialogProvider API, but there was no other way to get call backs from the events as to directly add listeners using the corresponding AWT control interfaces. This is a very inconvenient way to use dialogs created with the Dialog Editor.

From OpenOffice.org 2.0.4 also component methods can be bound to control events. The following chapters describe both how the binding to component methods is done in Dialog Editor and how the component has to be designed to use this mechanism.

Assigning Component Methods to Control Events
How a dialog is generally designed in the Basic IDE Dialog editor is described in First Steps with OpenOffice Basic. The assignment of macros to control events is also described there in the sub chapter Adding Event Handlers, but the Assign Action dialog showed in the following illustration can also be used to bind component methods to control events.



Instead of pressing the button the  button has to be used. It opens an Assign Component dialog.



Besides the standard buttons this dialog only contains an edit field to enter the name of the Component's method the event should be bound to. Unlike in the case of assigning macros it's not possible to browse to a component's methods because at design time no component instance exists. So the name has to be entered by hand.

The next illustration shows how the new assignment is shown in the Assign Action dialog.



The implementation of methods that should be assigned to events is explained in the following chapter.

Using Dialogs in Components
In general components using dialogs are like any other component. But they need some additional code to instantiate and display the dialog(s) to be used and to accept the events created by the dialog controls.

Instantiate and display a dialog
To do this an extended version of the com.sun.star.awt.DialogProvider service - described in chapter Scripting Framework - has to be used. The extended service version com.sun.star.awt.DialogProvider2 supports com.sun.star.awt.XDialogProvider2 providing an additional method com.sun.star.awt.XDialog createDialogWithHandler(...) that allows to pass an interface when creating the dialog. This interface will be used as event handler and called if events are bound to the component.

The following code is taken from the DialogComponent SDK example that can be found in SDK/examples/DevelopersGuide/Components and shows how a dialog is created and displayed using the DialogProvider2 service:

The variable  is the com.sun.star.uno.XComponentContext interface passed to the component while initialisation. If the dialog that should be created is placed inside a document a com.sun.star.frame.XModel interface  representing this document has to be passed. It's used as argument to initialise the DialogProvider service enabling the access to the document's Dialog Libraries. If  is null the dialog has to be placed in the application library container. This also has to be reflected in the DialogURL passed to the method.

Example code for a Basic/Dialog library  placed in a document:

Example code for a Basic/Dialog library  placed in "My Macros":

The dialog contained in the DialogComponent.odt sample document in SDK/examples/DevelopersGuide/Components/DialogComponent looks like this.



The button labels show which component method is called in each case. The next chapter explains how these methods can be implemented inside the component. Method "doit3" isn't implemented at all. It's called in the sample dialog to show the resulting error message:



Accept events created by dialog controls
The event handling functionality can be implemented in two different ways. The test component described here uses both ways.

The first way is to implement the generic handler interface com.sun.star.awt.XDialogEventHandler containing two methods:

If an event occurs that is bound to a component method and the component implements this interface, the method  will be called first, with the method name used in the event binding passed as   parameter. In this example this would be:

points to the same dialog instance that has been returned by the  method. Event represents the event object originally passed to the awt listener method. E.g. in case of the "When initiating" event used in this example the corresponding awt listener interface is com.sun.star.awt.XActionListener and an com.sun.star.awt.ActionEvent is passed to its  method when the event occurs. This  object will also be passed to. The Event object has to be passed as any, because other events use different listener interfaces with other event object types. returns a bool value. Returning true means that the event has been handled.

The method  should return the names of all methods handled by. It's intended for later use, especially to expand the user interface to allow browsing a component's methods.

If the event has not been handled, because  returns false or com.sun.star.awt.XDialogEventHandler isn't supported at all by the component, the DialogProvider uses the com.sun.star.beans.Introspection service to detect if one of the following methods is provided by one of the interfaces supported by the component:

or

The second method is only used if the first one is not available. In this example the component would have to support an interface containing a method  with one of these signatures. It also has to support com.sun.star.lang.XTypeProvider because otherwise the introspection mechanism does not work.

As already mentioned the sample component supports both ways to implement handler methods. com.sun.star.awt.XDialogEventHandler is implemented like this:

The implementation is very simple to show only the logic. For the two handled method names the method displays a MessageBox and returns true. Otherwise false is returned.

The other methods bound to the sample dialog control events are implemented using the other way. The interface com.sun.star.test.XTestDialogHandler looks like this:

Besides the already described  method three methods are defined to handle events. and  are implemented very simple and only display a message box:

The method copy text shows, how the passed XDialog interface can be used to access controls on the dialog itself. The details are not described here. For more information see Creating Dialogs at Runtime.

Simple components using dialogs can be realized very easily by supporting  as then no own interfaces have to be created. For complex components it could make more sense to define handler interfaces to avoid a huge switch/case blocks in.