Creating a new component

For the Eclipse plugin, a UNO component is a UNO project. This tutorial will explain how to easily create a new UNO component using the Eclipse plugin. We will now assume that you have very simple needs: the component that will be created is a “Hello world” service and its implementation. Creating a component defining and implementing more services is a bit more complex and need advanced Java UNO knowledge.

There are several ways to create a UNO component project using the plugin:

Figure 6.: New UNO-IDL project item

the first one is the File > New > Project menu entry and choose the UNO > UNO-IDL Project item as shown by the illustration 6.
the second one is the icon in the toolbar representing a blue folder with a star as shown by the illustration 7.

Figure 7.: New UNO-IDL project icon

Then you only have to follow the wizard to create your UNO component project, its specification and a skeleton of implementation. This wizard is composed of several pages:

The main configuration page to define the general project properties
The implementation language configuration page.
The service configuration page
The interface configuration page

After all these steps you can get a running component... doing nothing. The next sections will describe the different wizard pages and where to place your code.

The project configuration page

The first page in the project wizard is the only page containing fields that need to be filled. All the others have default values to help you through the component creation. In our case, we will need all the pages to explain them all and define some mew methods and attributes in our component.

Figure 8.: New UNO-IDL project wizard page

Project name: is the component name, in our case, it will be “Helloworld”
Location: is the directory on your computer where the project will be created. You can change the default one by deselecting the Use default check box. The default location of each Eclipse project is a directory with your project name in the current Eclipse workspace. Please avoid spaces in this path on Windows: it could prevent your component to be built.
Root package: is the name of the first module of your component. It generally composed of two parts: the vendor name (here my.company) and the project name (here helloworld).
Used SDK: selects the LibreOffice SDK which will be used to develop the component. You generally will have only one SDK in the list, but you can add others in the preferences or by clicking on the Configure SDKs button.
Used LibreOffice: selects the version of LibreOffice to use to develop the component. As for the SDK, you will generally have only one entry in the list, but you can add others in the preferences or by clicking on the LibreOffice Installations button.
Programming language: selects the programming language for the component implementation. For the moment, there is only Java available, however C++ and python are planned.

The implementation language configuration page

This page depends on the chosen language. For Java, the default values should be kept: they define which class is the main class of the component. The component's main class contains some code mapping the services to their implementation.

The service configuration page

Figure 9.: Service configuration page

Module: corresponds to the UNO-IDL module where to add the interface. If the text field is left empty, the interface will be added in the root module of the component (filled in the project wizard).
Service name: is the service name. By keeping the default value, you will be able to define your own interface using the interface configuration page. Otherwise, you can reuse an existing interface.
Published: specifies if the interface is published or not. The published notion is translated into a keyword in UNO-IDL language. Declaring a UNO-IDL type as published means that it will not change in future releases: we will keep it unchecked because our component is really far from being a stable API.

The interface configuration page

Figure 10.: Interface configuration page

Module: corresponds to the UNO-IDL module where to add the interface. If the text field is left empty, the interface will be added in the root module of the component (filled in the project wizard).
Interface name: is the interface name. By convention, we generally name a interface beginning with an “X”. In this tutorial case, the interface will be named Xhelloworld.
Inherited interfaces: is a list of all the interfaces from which the one that is about to be created will inherit. All the UNO-IDL interfaces are inheriting more or less directly from the com::sun::star::uno::XInterface type. As the XHelloworld interface is very easy, no super interface will be added: that will implicitly define XInterface as the only parent for the new interface.
- “?” column: specifies if the interface inheritance is mandatory or not. If the box is checked, thus the interface inheritance is optional and may not be implemented.
- “Add” and “Del” buttons: allows to add an interface to the inherited ones or removing the selected interface.
Members: is a list of all the methods and properties of the interface. See the explanations about the members some lines below. In this tutorial, just create one string sayHello([in] boolean isBadBoy) method and a LadyName property.
Published: specifies if the interface is published or not. The published notion is translated into a keyword in UNO-IDL language. Declaring a UNO-IDL type as published means that it will not change in future releases: we will keep it unchecked because our component is really far from being a stable API.

A UNO interface can contain two kind of members: methods and properties. When clicking on the Add button near the members' list, the following window will be shown. When double-clicking on a line in the members' list, you will edit the corresponding member through the same window.

When the window is opened to create a new member, you can choose whether the member will be a property or a method. The name and returned type fields are always present, but the lower part of the dialog is different for a method and a property.

Figure 11.: Interface member creation dialog

The arguments list: defines the name, type and direction of the parameters of the method. Simply click on the cell to edit it.
Read-only and Bound check boxes: selecting these boxes sets the corresponding IDL flag on the property.

Note

You can use Ctrl+Space to complete the type name in the Return type field and Type column.

Writing the implementation

After having completed the wizard, you need to write the component implementation. Hopefully a skeleton has been generated and opened: you just need to complete the code where there are some TODOS. The generated project contains the following directories and files to know:

source: directory containing your Java implementation classes
build: directory containing all the generated temporary files, such as the results of the specification files (.idl files) compilation (.urd files) or the class files corresponding to the specifications (.class files)
idl: directory containing the specifications of the component
types.rdb: generated UNO types registry from which the classes files will be generated
JRE and the jars: are describing the classpath of the component. They are visible only in the Java package explorer. The LibreOffice jars are changed if the LibreOffice version associated to the project is changed. In a future version, they will be packed in a user library to take less space in the tree.

The generated skeleton already contains the methods for the implementation registration. The only things to modify are:

Change the code of the setters and getters for the defined properties
Change the code of the defined methods.

The Eclipse integration even manages the libraries needed by your implementation. Let us imagine, that we want to use the Fraction class from the Apache common-math jar. Download this jar from the Apache website, and import the common-math-1.1.jar file into your component project: for example in a lib directory. Add the jar to the project build path in the same way than in any other Eclipse Java project and use it:

// my.company.helloworld.XHelloworld:
private String mLadyName = "";

public String getLadyName()
{
    return mLadyName;
}
public void setLadyName(String the_value)
{
    mLadyName = the_value;
}
public String sayHello(boolean isBadBoy)
{
    String hello = "Hello Mrs. " + getLadyName();
    if (isBadBoy) {
        Fraction f = new Fraction(1, 3);
        hello = "A third is " + f.doubleValue();
    }
    return hello;
}

The above code show you what could be an implementation of our component. Now, there is only to package it properly and test it.