Typically, a listener in a LibreOffice or OpenOffice client, for example for dispatch commands, but not necessarily so.
Topics
About: UNO (Universal Network Objects)
About: LibreOffice
About: Apache OpenOffice
About: C#
The table of contents of this article
- Starting Context
- Target Context
- Orientation
- Main Body
- 1: Motivation
- 2: Preparation
- 3: Create a UNO Component
- 4: Usage
Starting Context
- The reader has a basic knowledge on C#.
- The reader has a knowledge on how to connect his or her C# program to another UNO remote environment.
- The reader has a knowledge on what UNO is and how it is related to LibreOffice or Apache OpenOffice.
- The reader has a knowledge on the basic elements of UNO and the terminology used for them in this series.
Target Context
- The reader will know how to create and use his or her own UNO component in C#.
Orientation
There is an article on how to create and register any UNO Interface and generate the mapping images.
There is an article on how to create any UNO component in Java.
There is an article on how to create any UNO component in C++.
Main Body
Stage DirectionHere are Hypothesizer 7, Objector 63A, and Objector 63B in front of a computer.
1: Motivation
Hypothesizer 7
The primal motivation to create any UNO component is to let an instance of it (a UNO object) be handled from another programming language environment.
Objector 63B
Ah, then, it has nothing to do with me. I don't have any "another programming language environment".
Hypothesizer 7
Well, are you not creating a UNO program, madam?
Objector 63B
. . . I thought I was.
Hypothesizer 7
Do you not think now?
Objector 63B
. . . You are trapping me, aren't you?.
Hypothesizer 7
I am not trapping anybody.
Objector 63B
You are trapping me! Once I say I do, you are going to pounce on me!
Hypothesizer 7
. . . I do not pounce on anybody.
Objector 63B
You don't? Well, I am creating a C# program that does 'bootstrap' and handle a Calc sheet, if that is what you are asking.
Hypothesizer 7
Then, you are creating a UNO program and have another programming language environment, madam.
Objector 63B
You pounced on me! I knew it!
Hypothesizer 7
. . . It was not "pounc"ing at all; I just have clarified the situation.
Objector 63B
What's the situation?
Hypothesizer 7
Your C# program will connect to a LibreOffice or Apache OpenOffice instance, which is another programming language environment.
Objector 63B
"a LibreOffice or Apache OpenOffice instance"? I don't have such a thing.
Hypothesizer 7
Yes, you do; you do 'bootstrap', which connects to it, after starting one if it does not exist.
Objector 63B
I don't know what you are talking about.
Hypothesizer 7
You should understand how UNO works.
Objector 63B
. . . Anyway, I do not do any programming in the "another programming language environment".
Hypothesizer 7
That is not the issue, madam.
Objector 63A
I know that there is another programming language environment, but I don't need to create any UNO component of my own.
Hypothesizer 7
Well, are you sure, sir?
Objector 63A
My purpose is to handle some existing UNO components, like Writer or something documents or something. Why do I want to create my own UNO component?
Hypothesizer 7
A typical case is that you create a listener.
Objector 63A
"listener"?
Hypothesizer 7
As the broadcaster-listener pattern is rather prevalent in LibreOffice or Apache OpenOffice, one usually bumps into it if he or she goes some extent in UNO programming.
Objector 63A
. . .
Hypothesizer 7
A typical example is executing a UNO dispatch command.
Objector 63A
What about it? I can execute a UNO dispatch command without any listener.
Hypothesizer 7
You can, in a lazy way, but if you use a listener, you can get the whole available information from the execution.
Objector 63A
. . . So, listeners are the sole occasions to create UNO components . . .
Hypothesizer 7
Not necessarily so. You can pass your UNO object into a macro or something, or even create a C# UNO server in which your UNO components live.
Objector 63A
. . . I don't understand what you are talking about.
Hypothesizer 7
Some people may.
2: Preparation
Hypothesizer 7
If your UNO component implements some of your UNO interfaces, you have to have created them and generated their C# mapping image according to the previous article.
Objector 63B
"UNO interfaces"?
Hypothesizer 7
If you do not need them, you do not need to worry about them.
3: Create a UNO Component
Hypothesizer 7
This is a typical code piece that creates a UNO component.
@C# Source Code
namespace theBiasPlanet {namespace unoUtilitiesTests {namespace localUnoObjectsTest1 {using System;using uno.util;using unoidl.com.sun.star.lang;public class TestUnoComponent: WeakBase, XServiceInfo {public TestUnoComponent () {}~TestUnoComponent () {}public virtual String getImplementationName () {return "not specified";}public virtual Boolean supportsService (String a_serviceName) {return false;}public virtual String [] getSupportedServiceNames () {return new String [0];}}}}}
Objector 63B
. . . Does that mean that my UNO component has to extend "WeakBase" and "XServiceInfo", always?
Hypothesizer 7
No. 'uno.util.WeakBase' is a helper class that has already implemented some UNO interfaces ('unoidl.com.sun.star.uno.XWeak' and 'unoidl.com.sun.star.lang.XTypeProvider', to be exact), and if your UNO component does not need to implement those UNO interfaces, it does not need to extend 'WeakBase'.
Objector 63B
Being told "if" . . .
Hypothesizer 7
'XWeak' is for making any instance of it be able to be weakly-pointed.
Objector 63B
"weakly-pointed"?
Hypothesizer 7
As is detailed in a previous article, 'weakly-pointed' means that the usage count of the instance is incremented just before the instance is really accessed and is decremented immediately after the access is finished.
Objector 63B
. . .
Hypothesizer 7
. . . but if you do not understand it, that is probably because you do not need it.
On the other hand, 'XTypeProvider' is for making it accessible from macro languages.
Objector 63B
I'm not particularly supposing it to be accessed from any macro language, but making it accessible doesn't harm anything, does it?
Hypothesizer 7
It does not.
Objector 63B
OK.
Hypothesizer 7
As for "XServiceInfo", it is cited just as a harmless example, and you usually do not need to use it.
Your UNO component can just extend your necessary UNO interface(s) instead of it.
Objector 63B
What is my necessary UNO interface?
Hypothesizer 7
I do not know what your UNO component needs. . . . If your UNO component is a listener, what the broadcaster requires are what your UNO component needs.
4: Usage
Hypothesizer 7
The assembly file that contains the UNO component, of course, has to be referred to from your program.
Objector 63B
How can it be referred to?
Hypothesizer 7
That is just a C# problem: it can be referred to as any usual .NET assembly can be.
Anyway, in order to create any instance of the UNO component in the C# environment, you can just call any constructor of the class.
Objector 63B
And then?
Hypothesizer 7
What do you mean by "then"?
Objector 63B
How can I use the instance?
Hypothesizer 7
You can use it as an ordinary C# object in the C# environment.
Objector 63B
Is that meaningful? It's just an ordinary C# object!
Hypothesizer 7
It is meaningful because it can be passed into a broadcaster, for example.
Objector 63B
Hmm.
Hypothesizer 7
If you handle the UNO object from another environment, of course, you will have to handle it as it is a remote UNO object.
Objector 63B
How should the UNO component class be referred to from the another environment?
Hypothesizer 7
The class is not referred to from the another environment.
Objector 63B
Huh? Are you nuts? It has to, right?
Hypothesizer 7
No. The another environment is, for example, a Java environment, which, of course, cannot refer to the C# class.
Objector 63B
Can't it?
Hypothesizer 7
How can a Java environment refer to a C# class?
Objector 63B
UNO manages it, right?
Hypothesizer 7
UNO employs UNO proxies to enable inter-environments objects accesses, not let a C# class be referred to from a Java environment. . . . You should understand how UNO works.
