Apache OpenOffice Wiki - User contributions [en]

Using Cpp with the OOo SDK

2014-07-11T07:47:07Z

Global667: Change Formating look now more like extensions main page

{{Documentation/Banner}}

This site is about using C++ as a language to program OpenOffice extensions.
==== Common ====
* [[CppSDKAuthors|About the Author and Contributors]]
* [[GNU_Lesser_General_Public_License|GNU Lesser General Public License]]
* [[SDKInstallation|How to install the SDK and compile the C++ examples]]
* [[SDKCppLanguage|The UNO C++ Language]]
* [[UNO_automation_with_a_binary_(executable)|OpenOffice.org's UNO automation with a binary (executable)]]
==== Writer, Calc, Draw and Impress ====
* [[Programming OooWriter |Programming OooWriter with C++]]
* [[Calc/API/Programming|OpenOffice Calc]]
* [[Programming_OOoDraw_and_OOoImpress|Programming OOoDraw and OOoImpress with C++]]
* [[Working_with_Shapes |Working with Shapes in C++]]
==== General Utilities ====
*[[Playing_with_Window_Toolkit_AWT|Playing with Window Toolkit AWT]]
*[[Executing_an_OOoBasic_macro_with_Cpp|Executing an OOoBasic macro with C++]]
* [[IDL_Files_and_Cpp|IDL Files and C++]]
* [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]]
* [[Constructing_Helpers|Constructing Helpers]]
==== Components ====
* [[Constructing_Components|Constructing Components in C++]]
* [[Component_and_Dialog|Managing a Dialog in a Component]]
* [[Going_further_with_Dialog_and_Component|Going further with Dialog and Components]]
* [[Writing_Professional_Components|Writing professional Components]]
==== AddOns ====
* [[Add-on|Constructing an Addon]]
* [[CompleteAddIn | OOoCalc AddOn in C++]]
* [[XML_and_Filter |XML, Filters and Files]]
{{Documentation/Caution|I have decided to give up with this C++ documentation. My last work was to add two chapters in summer 2009. I have done nothing more during last year. I only want to say this document is completely free, unfortunatly is not finished (particularly with addon and dialog). Please let this caution banner for a year and remove it after because tradition in OpenOffice documentation is to remove author's names. After a year, it would be also great to remove my name everywhere it appears in other chapters. Thank you in Advance. 08:52, 26 August 2010 (UTC)}}
= See also=
==== General ====
* [[FR/Documentation/Cpp_Guide|French version of this document]].
* [[Documentation/DevGuide/OpenOffice.org_Developers_Guide | Developer's Guide]]
* [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno|C++ and UNO tutorial]]
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* [[Tutorial_UNO_Library|UNO tutorial]]
* [[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://udk.openoffice.org/common/man/concept/unointro.html UNO Introduction]
* [http://www.oooforum.org/forum/viewtopic.phtml?t=8702 Working with a database in C++] (not tackled in this document at the moment).
* [[Compiler_versions_used_by_port_maintainers_and_release_engineers|Compiler versions used by port maintainers and release engineers]]
==== Coding ====
* [[Writing_correct_Cplusplus|Writing correct C++]]
* [[MakeFile|Using make utility with SDK]]
* [[Writing_warning-free_code|Writing warning-free code]]
* [[Debugging |Debugging]]

[[Category:Tutorial]]
[[Category:Cpp]]
[[Category:Documentation/Developer's Guide]]
[[Category:Uno]]
[[Category:Article]]

Using Cpp with the OOo SDK

2014-07-11T02:10:24Z

Global667: Structuring changed

{{Documentation/Banner}}

This site is about using C++ as a language to program OpenOffice extensions.
* Common
** [[CppSDKAuthors|About the Author and Contributors]]
** [[GNU_Lesser_General_Public_License|GNU Lesser General Public License]]
** [[SDKInstallation|How to install the SDK and compile the C++ examples]]
** [[SDKCppLanguage|The UNO C++ Language]]
** [[UNO_automation_with_a_binary_(executable)|OpenOffice.org's UNO automation with a binary (executable)]]
* Writer, Calc, Draw and Impress
** [[Programming OooWriter |Programming OooWriter with C++]]
** [[Calc/API/Programming|OpenOffice Calc]]
** [[Programming_OOoDraw_and_OOoImpress|Programming OOoDraw and OOoImpress with C++]]
** [[Working_with_Shapes |Working with Shapes in C++]]
* General Utilities
**[[Playing_with_Window_Toolkit_AWT|Playing with Window Toolkit AWT]]
**[[Executing_an_OOoBasic_macro_with_Cpp|Executing an OOoBasic macro with C++]]
** [[IDL_Files_and_Cpp|IDL Files and C++]]
** [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]]
** [[Constructing_Helpers|Constructing Helpers]]
* Components
** [[Constructing_Components|Constructing Components in C++]]
** [[Component_and_Dialog|Managing a Dialog in a Component]]
** [[Going_further_with_Dialog_and_Component|Going further with Dialog and Components]]
** [[Writing_Professional_Components|Writing professional Components]]
* AddOns
** [[Add-on|Constructing an Addon]]
** [[CompleteAddIn | OOoCalc addin in C++]]
** [[XML_and_Filter |XML, Filters and Files]]
{{Documentation/Caution|I have decided to give up with this C++ documentation. My last work was to add two chapters in summer 2009. I have done nothing more during last year. I only want to say this document is completely free, unfortunatly is not finished (particularly with addon and dialog). Please let this caution banner for a year and remove it after because tradition in OpenOffice documentation is to remove author's names. After a year, it would be also great to remove my name everywhere it appears in other chapters. Thank you in Advance. 08:52, 26 August 2010 (UTC)}}
= See also=
* General
** [[FR/Documentation/Cpp_Guide|French version of this document]].
** [[Documentation/DevGuide/OpenOffice.org_Developers_Guide | Developer's Guide]]
** [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno|C++ and UNO tutorial]]
** Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
** [[Tutorial_UNO_Library|UNO tutorial]]
** [[Tutorial_UNO_IDL|UNO IDL]]
** [[Uno/Article/Types%26Reflection]]
** [http://udk.openoffice.org/common/man/concept/unointro.html UNO Introduction]
** [http://www.oooforum.org/forum/viewtopic.phtml?t=8702 Working with a database in C++] (not tackled in this document at the moment).
** [[Compiler_versions_used_by_port_maintainers_and_release_engineers|Compiler versions used by port maintainers and release engineers]]
* Coding
** [[Writing_correct_Cplusplus|Writing correct C++]]
** [[MakeFile|Using make utility with SDK]]
** [[Writing_warning-free_code|Writing warning-free code]]
** [[Debugging |Debugging]]

[[Category:Tutorial]]
[[Category:Cpp]]
[[Category:Documentation/Developer's Guide]]
[[Category:Uno]]
[[Category:Article]]

Using Cpp with the OOo SDK

2014-07-11T01:57:08Z

Global667: Formating

{{Documentation/Banner}}
[[Image:HomePageCpp.png]]

This site is about using C++ as a language to program OpenOffice extensions.
* Common
** [[CppSDKAuthors|About the Author and Contributors]]
** [[GNU_Lesser_General_Public_License|GNU Lesser General Public License]]
** [[MakeFile|Appendix : Using make utility]] with SDK
** [[SDKInstallation|How to install the SDK and compile the C++ examples]]
** [[SDKCppLanguage|The UNO C++ Language]]
** [[UNO_automation_with_a_binary_(executable)|OpenOffice.org's UNO automation with a binary (executable)]]
* Writer, Calc, Draw and Impress
** [[Programming OooWriter |Programming OooWriter with C++]]
** [[Calc/API/Programming|OpenOffice Calc]]
** [[Programming_OOoDraw_and_OOoImpress|Programming OOoDraw and OOoImpress with C++]]
** [[Working_with_Shapes |Working with Shapes in C++]]
* General Utilities
**[[Playing_with_Window_Toolkit_AWT|Playing with Window Toolkit AWT]]
**[[Executing_an_OOoBasic_macro_with_Cpp|Executing an OOoBasic macro with C++]]
** [[IDL_Files_and_Cpp|IDL Files and C++]]
** [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]]
** [[Constructing_Helpers|Constructing Helpers]]
* Components
** [[Constructing_Components|Constructing Components in C++]]
** [[Component_and_Dialog|Managing a Dialog in a Component]]
** [[Going_further_with_Dialog_and_Component|Going further with Dialog and Components]]
* AddOns
** [[Add-on|Constructing an Addon]]
** [[CompleteAddIn | OOoCalc addin in C++]]
** [[Writing_Professional_Components|Writing professional Components]]
** [[XML_and_Filter |XML, Filters and Files]]
{{Documentation/Caution|I have decided to give up with this C++ documentation. My last work was to add two chapters in summer 2009. I have done nothing more during last year. I only want to say this document is completely free, unfortunatly is not finished (particularly with addon and dialog). Please let this caution banner for a year and remove it after because tradition in OpenOffice documentation is to remove author's names. After a year, it would be also great to remove my name everywhere it appears in other chapters. Thank you in Advance. 08:52, 26 August 2010 (UTC)}}
= See also=
* General
** [[FR/Documentation/Cpp_Guide|French version of this document]].
** [[Documentation/DevGuide/OpenOffice.org_Developers_Guide | Developer's Guide]]
** [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno|C++ and UNO tutorial]]
** Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
** [[Tutorial_UNO_Library|UNO tutorial]]
** [[Tutorial_UNO_IDL|UNO IDL]]
** [[Uno/Article/Types%26Reflection]]
** [http://udk.openoffice.org/common/man/concept/unointro.html UNO Introduction]
** [http://www.oooforum.org/forum/viewtopic.phtml?t=8702 Working with a database in C++] (not tackled in this document at the moment).
** [[Compiler_versions_used_by_port_maintainers_and_release_engineers|Compiler versions used by port maintainers and release engineers]]

* Coding
** [[Writing_correct_Cplusplus|Writing correct C++]]
** [[Writing_warning-free_code|Writing warning-free code]]
** [[Debugging |Debugging]]

[[Category:Tutorial]]
[[Category:Cpp]]
[[Category:Documentation/Developer's Guide]]
[[Category:Uno]]
[[Category:Article]]

Using Cpp with the OOo SDK

2014-07-11T01:53:19Z

Global667: Formating

{{Documentation/Banner}}
[[Image:HomePageCpp.png]]
This site is about using C++ as a language to program OpenOffice extensions.
* Common
** [[CppSDKAuthors|About the Author and Contributors]]
** [[GNU_Lesser_General_Public_License|GNU Lesser General Public License]]
** [[MakeFile|Appendix : Using make utility]] with SDK
** [[SDKInstallation|How to install the SDK and compile the C++ examples]]
** [[SDKCppLanguage|The UNO C++ Language]]
** [[UNO_automation_with_a_binary_(executable)|OpenOffice.org's UNO automation with a binary (executable)]]
* Writer, Calc Draw and Impress
** [[Programming OooWriter |Programming OooWriter with C++]]
** [[Calc/API/Programming|OpenOffice Calc]]
** [[Programming_OOoDraw_and_OOoImpress|Programming OOoDraw and OOoImpress with C++]]
** [[Working_with_Shapes |Working with Shapes in C++]]
* General Utilities
**[[Playing_with_Window_Toolkit_AWT|Playing with Window Toolkit AWT]]
**[[Executing_an_OOoBasic_macro_with_Cpp|Executing an OOoBasic macro with C++]]
* [[IDL_Files_and_Cpp|IDL Files and C++]]
* [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]]
* [[Constructing_Helpers|Constructing Helpers]]
* [[Constructing_Components|Constructing Components in C++]]
* [[Component_and_Dialog|Managing a Dialog in a Component]]
* [[Going_further_with_Dialog_and_Component|Going further with Dialog and Components]]
* AddOns
** [[Add-on|Constructing an Addon]]
** [[CompleteAddIn | OOoCalc addin in C++]]
** [[Writing_Professional_Components|Writing professional Components]]
** [[XML_and_Filter |XML, Filters and Files]]
{{Documentation/Caution|I have decided to give up with this C++ documentation. My last work was to add two chapters in summer 2009. I have done nothing more during last year. I only want to say this document is completely free, unfortunatly is not finished (particularly with addon and dialog). Please let this caution banner for a year and remove it after because tradition in OpenOffice documentation is to remove author's names. After a year, it would be also great to remove my name everywhere it appears in other chapters. Thank you in Advance. 08:52, 26 August 2010 (UTC)}}
= See also=
* General
** [[FR/Documentation/Cpp_Guide|French version of this document]].
** [[Documentation/DevGuide/OpenOffice.org_Developers_Guide | Developer's Guide]]
** [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno|C++ and UNO tutorial]]
** Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
** [[Tutorial_UNO_Library|UNO tutorial]]
** [[Tutorial_UNO_IDL|UNO IDL]]
** [[Uno/Article/Types%26Reflection]]
** [http://udk.openoffice.org/common/man/concept/unointro.html UNO Introduction]
** [http://www.oooforum.org/forum/viewtopic.phtml?t=8702 Working with a database in C++] (not tackled in this document at the moment).
** [[Compiler_versions_used_by_port_maintainers_and_release_engineers|Compiler versions used by port maintainers and release engineers]]

* Coding
** [[Writing_correct_Cplusplus|Writing correct C++]]
** [[Writing_warning-free_code|Writing warning-free code]]
** [[Debugging |Debugging]]

[[Category:Tutorial]]
[[Category:Cpp]]
[[Category:Documentation/Developer's Guide]]
[[Category:Uno]]
[[Category:Article]]

SDKCppLanguage

2014-07-11T00:56:00Z

Global667: /* Our starting Example : Simple Binaries (Executable) */ formating

{{Documentation/Banner}}
{{Documentation/NeedsRework}}
=The UNO C++ Language=
The aim of this chapter is to explain peculiarities of the C++ language in the UNO environment and not to provide skills on traditional C++. To put it differently, I want to give here the UNO/C++ background, quite helpful in getting us started.
You can find e-Books on C++ [http://www.smart2help.com/e-books/ here].

See also [[Uno/Article/Understanding_Uno|Understanding Uno]], [[Documentation/DevGuide/FirstSteps/Objects%2C_Interfaces%2C_and_Services|Objects, Interfaces, and Services]] and [[Documentation/BASIC_Guide/UNO|OOoBasic UNO Guide]] for a start with UNO.

== Our starting Example : Simple Binaries (Executable) ==

We want now to start with a SDK example. The purpose of the example presented is to create an executable which interacts with OpenOffice.org. We can imagine two kind of interactions : direct interaction with OpenOffice.org or interaction with one of OOo's shared library. We focus on this second case where the makefile is simpler. The shared library involved is then cppuhelper.uno.so (cppuhelper.uno.dll under Windows). Former case will be examined later.
I assume (I know nobody of the SDK team) this example is given to provide the simplest example we can do with the SDK. This is the Lifetime example: see at “<SDK_Folder>/examples/DevelopersGuide/ProfUNO/Lifetime”

Before diving into the examples, you will need to set up your programming environment so you can create UNO programs. What's required depends on what platform you're working. This is shown in the first example with LINUX platform.
To check this example you only have to launch the makefile :
{{Documentation/Linux|
<pre>
cd <SDK_Folder>
./setsdkenv_unix
cd examples/DevelopersGuide/ProfUNO/Lifetime
make
make ProfUnoLifetime.runexe
</pre>
}}
The last command line only launch the binary executable “ProfUnoLifetime” which interact with cpphelper.uno.so (cppuhelper.uno.dll under Windows) even if OpenOffice.org is not running.
This example creates and releases an object, nothing more. The constructor and destructor of the object only write out a message. Its little size allows us to give its code here:
<source lang="cpp">
// Listing 1 First Example (from SDK)
// C++
#include <stdio.h>
#include <cppuhelper/weak.hxx>

class MyOWeakObject : public ::cppu::OWeakObject
{
public:
MyOWeakObject()
{
fprintf( stdout, "constructed\n" );
}
~MyOWeakObject()
{
fprintf( stdout, "destructed\n" );
}
};

void simple_object_creation_and_destruction()
{
// create the UNO object
com::sun::star::uno::XInterface * p = new MyOWeakObject();

// acquire it, refcount becomes one
p->acquire();
fprintf( stdout, "before release\n" );

// release it, refcount drops to zero
p->release();
fprintf( stdout, "after release\n" );
}
int main( char * argv[] )
{
simple_object_creation_and_destruction();
return 0;
}
</source>

The two methods acquire and release will be encountered later. What exactly they do is not important for the moment. This example shows us how to write a class which inherits from an other class, how to write and call methods and how to instantiate the class.
All the listings given below only need to modify this C++ code compile it and run it. You can therefore use the same makefile by possibly changing the name of the source file (tackled in next section).

== Types ==
The [[Documentation/DevGuide/FirstSteps/Common_Types|UNO types]] are given in the table below :
; UNO Types
{| border cellspacing="0" width="550"
|- style = "background:#b3e2d1;text-align:center"
| |UNO||Type description||Java||C++||Basic
|- style="text-align:center"
| char||16-bit unicode character type||char||sal_Unicode || -
|- style="text-align:center"
|boolean ||boolean type; true and false ||boolean ||sal_Bool||Boolean
|- style="text-align:center"
|byte ||8-bit ordinal type||byte ||sal_Int8 ||Integer
|- style="text-align:center"
|short ||signed 16-bit ordinal type||short ||sal_Int16 ||Integer
|- style="text-align:center"
|unsigned short||unsigned 16-bit ordinal type||- ||sal_uInt16 ||-
|- style="text-align:center"
|long ||signed 32-bit ordinal type||int ||sal_Int32 ||Long
|- style="text-align:center"
|unsigned long ||unsigned 32-bit type ||- ||sal_uInt32 ||-
|- style="text-align:center"
|hyper||signed 64-bit ordinal type||long ||sal_Int64 ||-
|- style="text-align:center"
|unsigned hyper ||unsigned 64-bit ordinal type||- ||sal_uInt64 ||-
|- style="text-align:center"
|float ||processor dependent float||float ||float (IEEE float) ||Single
|- style="text-align:center"
|double ||processor dependent double||double||double (IEEE double)||Double
|}

The UNO's column represents all the types you can find in the specifications files : IDL files. We describe IDL files later (see chapter 10). The C++ column is what we are interested in when we program with this language. If you want to check the different programs given in this chapter, you can use the <OpenOffice.org1.1_SDK>/examples/DevelopersGuide/ProfUNO/Lifetime
example. Replace object_lifetime.cxx completely with the listing below (don't forget to save the old file)

<source lang="cpp">
// Listing 2 A short UNO Program
// C++
#include <stdio.h>
#include <cppuhelper/bootstrap.hxx>

main( ) {
sal_Int32 var1;
var1 = 34;
printf("The var1 value is : %d\n",var1);
return 0;
}
</source>

then launch
<pre>
make ALL
make ProfUnoLifetime.runexe
</pre>
and it works. Don't forget ./setsdkenv_unix (only one time) on Linux and the corresponding command (setsdkenv_windows.bat) on Windows.

==[[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno#Sequence|Sequences]]==
We can find also good materials in Developer's guide on [[Documentation/DevGuide/FirstSteps/Sequence|Sequence]].
A sequence is an abstract view of a set of UNO types with a variable number of elements. As first example, we give a very simple program:

<source lang="cpp">
// Listing 3 UNO Sequences
// C++
#include <stdio.h>
#include <cppuhelper/bootstrap.hxx>
#include <com/sun/star/uno/Sequence.hxx>
using namespace com::sun::star::uno;

main( ) {
Sequence < sal_Int32 > SetOfInt(5);
//var1 = 34;
SetOfInt[2]=44;
printf("The value is : %d\n",SetOfInt[2]);
return 0;
}
</source>

The important things to notice are as follows:
* the type of each element of the set is put between angular brackets: "<" and ">". In the example above sal_int32 is the type.
* declaration of sequence is done with parentheses "(" and ")" and the number of elements of the sequence between them. In the example above a sequence of five sal_Int32 elements is declared.
* accessing elements of the sequence is done with "[" and "]" and an index between them (generaly called subscript operator). This allows us to say that sequences are referenced like arrays. But they are different in some way, for instance they don't have a fixed size.
* We have to include Sequence.hxx file in a program when using Sequence. Note that this file is provided with the SDK and this not always the case for all hxx files (some of them have to be reconstructed).
We have to use the correct namespace with adding "using namespace ..." If you don't use this statement you have to write com::sun::star::uno::Sequence instead of Sequence.
A Sequence can be created with arbitrary UNO type but not with other types.
The object SetOfInt has many methods. We give an example to show some of them:
<source lang="cpp">
// Listing 4 Examples of using Sequence Methods
// C++
#include <stdio.h>
#include <cppuhelper/bootstrap.hxx>
#include <com/sun/star/uno/Sequence.hxx>
using namespace com::sun::star::uno;

main( ) {
Sequence < sal_Int32 > SetOfInt(5);
sal_Int32 *table;
SetOfInt[2]=44;
printf("The value is : %d\n",SetOfInt[2]);
// Tests whether the sequence has elements, i.e. elements count is greater than zero
if (SetOfInt.hasElements()) printf("Set not empty\n");
// Gets a pointer to elements array for reading and writing. If the sequence
// has a length of 0, then the returned pointer is undefined
table = SetOfInt.getArray();
table[4]=78;
printf("The value is : %d\n",SetOfInt[4]); // prints out 78
SetOfInt.realloc(7);
printf("New length : %d\n",SetOfInt.getLength()); // prints out 7
return 0;
}
</source>

The comments explain what is printed out when executing this example. The method realloc is particularly important: it allows the size of set to change.

Let us focus on using sequences in function or as parameter. An example is again more descriptive than a long text:

<source lang="cpp">
// Listing 5 Sequence and Parameters
// C++
// function
Sequence < sal_Int32 > initSequence(){
sal_Int32 sourceArray[5]={1,2,3,4,5};
Sequence < sal_Int32 > SeqOfInt(sourceArray,5);
return SeqOfInt;
}
// reference parameter
void initSequence2(Sequence < sal_Int32 > &SeqOfInt ) {
sal_Int32 sourceArray[4]={1,2,3,4};
Sequence < sal_Int32 > SeqOfInt2(sourceArray,4);
SeqOfInt=SeqOfInt2;
}
</source>
An obvious call could be :

<source lang="cpp">
// Listing 6 Sequence and Parameters (following)
// C++
SetOfInt = initSequence();
printf("New length : %d\n",SetOfInt.getLength()); // prints out 5
initSequence2(SetOfInt);
printf("New length : %d\n",SetOfInt.getLength()); // prints out 4
</source>
We cannot leave this section without adding that operators == and != are available with sequences. Note also that "toUnoSequence()", "getCppuSequenceType()" and "getCharSequenceCppuType()" are also member functions.

Passing a sequence into a function by value is, like a vector, somewhat inefficient because the function must make a copy of all elements. It's better to use a constant reference as shown below:
<source lang="cpp">
// Listing 7 The Constant Reference method
//C++
#include <iostream>
#include <cppuhelper/bootstrap.hxx>
#include <com/sun/star/uno/Sequence.hxx>
using namespace com::sun::star::uno;
using namespace std;

// Passing a Sequence by value using the Constant Reference method
void avoidCopy(const Sequence< double > &ConstRef){
// ConstRef[2]=6.7; would fail here
for(int i=0;i<ConstRef.getLength();i++)
cout<<ConstRef[i]<<" ";
cout<<endl;

}

main( ) {
Sequence < double > demo(5);
demo[0]=1.1;
demo[1]=2.1;
demo[2]=3.1;
demo[3]=4.1;
demo[4]=5.1;
avoidCopy(demo);
return 0;
}
</source>

See other material in Developer's Guide (UNO C++ Binding).

==Strings==

In C, a string is simply an array of characters that always includes a binary zero (often called the null terminator) as its final array element. UNO/C++ API manages strings with two classes: OUString and OString. The former uses Unicode characters.

; STRING UNO Type
{| border cellspacing="0" width="550"
|- style = "background:#b3e2d1;text-align:center"
| |UNO||Type description||Java||C++||Basic
|- style="text-align:center"
| string||String of 16-bit unicode characters ||Java.lang.string||::rtl::OUString || String
|}

But, if you want to use ASCII characters the latter class is for you.
===OUString and OString===
OUString and OString classes are designed for UNO programmers. Only OString can be used with a standard C printf. To put it differently OString is nearer to the common C ASCII strings (array of characters) than OUString (which is an array of Unicode).
But all strings managed by UNO API are OUString. That means, if you want to see something in the console, you have to convert OUString to OString. If you ask something to the user and want to pass it to UNO API, you have to convert OString to OUString. Then if you want to use the console (in general for testing) you have to learn first both conversions.

==== OUString to OString ====

If OUStr is a OUString object, we give this example for conversion:

<source lang="cpp">
// Listing 8 Converting OUString into OString
// C++
#include <rtl/string.hxx>

OString o = OUStringToOString( OUStr, RTL_TEXTENCODING_ASCII_US );
printf( "Conversion result : %s\n", o.pData->buffer );
</source>

==== OString to OUString ====
The inverse conversion is easy too :
<source lang="cpp">
// Listing 9 Converting OString into OUString
// C++
OUString foo;
foo = OUString::createFromAscii("Hi every body");
</source>

Here is a complete conversion example:

<source lang="cpp">
// Listing 10 A complete Example
// C++
#include <stdio.h>
#include <cppuhelper/bootstrap.hxx>
#include <rtl/string.hxx>
using namespace rtl;

main( ) {
OUString OUStr;
OUStr = OUString::createFromAscii("Hi every body");
OString OStr = OUStringToOString( OUStr, RTL_TEXTENCODING_ASCII_US );
printf( "OUStr was : %s\n", OStr.pData->buffer );
return 0;
}
</source>

We see that a rtl namespace has to be used. If not, please replace OUString by ::rtl::OUString.
OUString and OString objects are class type variables, and then the operations that can be performed on O(U)Strings take the form
<pre>
O(U)StringVariable.operation(argumentList)
</pre>
For example, if string1 and string2 are variables of type OUString, then
<pre>
string1.compareTo(string2)
</pre>
can be used to compare both strings. A function like compareTo(), which is part of the O(U)String-class is called a member function. The O(U)String class offers a large number of these member functions, as well as extensions of some well-known operators, like the assignment (=) and the comparison operator (==). These operators and functions are discussed in the following sections.
The OUString and OString methods are similar: we give a complete example which shows some of them:
<source lang="cpp">
// Listing 11 A more complete Example
// C++
#include <stdio.h>
#include <cppuhelper/bootstrap.hxx>
#include <rtl/string.hxx>
using rtl::OUString;
using rtl::OString;

main( ) {
OUString OUStr1,OUStr2;
OString OStr1, OStr2;
OStr1="Hi every body";
OStr2="every body";
OUStr1 = OUString::createFromAscii("Hi every body");
OUStr2 = OUString::createFromAscii("Hi every body");
// Returns the length of this string
printf("Length : %d\n",OUStr1.getLength()); // prints out 13
// Compares two strings
printf("CompareTo : %d\n",OUStr1.compareTo(OUStr2)); // prints out 0
// Compares two strings
// serviceName.equalsAsciiL( RTL_CONSTASCII_STRINGPARAM("my_module.MyService2") );
printf("equals : %d\n",OUStr1.equals(OUStr2)); // prints out 1
if (OUStr1.equals(OUStr2)) printf("OK\n");// prints out OK
// Compares two strings
printf("CompareToAscii : %d\n",OUStr1.compareToAscii(OStr1)); // prints out 0
// Compares two strings with a maximum count of characters
printf("CompareToAscii : %d\n",OUStr1.compareToAscii(OStr1),10); // prints out 0
// Perform a comparison of a substring in this string
// is "every body" in position 3 of OUStr1 ?
if (OUStr1.match(OUString::createFromAscii("every body"),3))
printf("match : OK\n"); //prints out match : OK
// Perform a comparison of a substring in this string
if (OUStr1.matchAsciiL(OStr2,OStr2.getLength(),3))
printf("matchAsciiL: OK\n");
// Returns the float value from this string
OUStr2 = OUString::createFromAscii("1.675");
printf("toFloat : %f\n",OUStr2.toFloat()); // prints out 1.675000
// Value Of :
OUStr1 = OUStr1.valueOf((float)1.56);
OStr1 = OUStringToOString( OUStr1, RTL_TEXTENCODING_ASCII_US );
printf( "Value of : %s\n", OStr1.pData->buffer );
// concat
OUStr2=OUStr2.concat(OUString::createFromAscii(" ..."));
OStr1 = OUStringToOString( OUStr2, RTL_TEXTENCODING_ASCII_US );
printf( "concat is : %s\n", OStr1.pData->buffer );
return 0;
}
</source>
We can also see in this program how the concat method (three last lines) is used. The toFloat() conversion method is not alone: toBoolean(), toChar(), toInt32(), toInt64() , toDouble(), toAsciiLowerCase() and toAsciiUpperCase() exist also. Now we terminate with presenting some other methods (see C++ material):

; String methods
{| border cellspacing="0" width="850"
|- style = "background:#b3e2d1;text-align:center"
| colspan="2"|Methods
|- style="text-align:center"
|indexOf( sal_Unicode ch, sal_Int32 fromIndex = 0 ) ||Returns the index within this string of the first occurrence of the specified character, starting the search at the specified index
|- style="text-align:center"
|sal_Int32 hashCode()||Returns a hashcode for this string
|- style="text-align:center"
|sal_int32 lastIndexOf(sal_Unicode ch )||Returns the index within this string of the last occurrence of the specified character, searching backward starting at the end
|- style="text-align:center"
|sal_Int32 lastIndexOf(sal_Unicode ch, sal_Int32 fromIndex ) ||Returns the index within this string of the last occurrence of the specified character, searching backward starting at the specified index
|- style="text-align:center"
|sal_Int32 lastIndexOf(const OUString & str ) || Returns the index within this string of the last occurrence of the specified substring, searching backward starting at the end
|- style="text-align:center"
|OUString copy(sal_Int32 beginIndex, sal_Int32 count ) OUString copy(sal_Int32 beginIndex ) ||Returns a new string that is a substring of this string
|- style="text-align:center"
|OUString replaceAt(sal_Int32 index, sal_Int32 count, const OUString & newStr ) ||Returns a new string resulting from replacing n = count characters from position index in this string with newStr
|- style="text-align:center"
|OUString replace(sal_Unicode oldChar, sal_Unicode newChar ) ||Returns a new string resulting from replacing all occurrences of oldChar in this string with newChar
|- style="text-align:center"
|OUString trim() ||Returns a new string resulting from removing white space from both ends of the string
|- style="text-align:center"
|OUString getToken(sal_Int32 token, sal_Unicode cTok, sal_Int32 & index ) ||Returns a token in the string
|}

I cannot close this section without giving a code found in OOo source /OOB680_m5/registry/source/regimpl.cxx
<source lang="cpp">
//Listing 11-b Printing out an OUString
// C++
void printString(rtl::OUString const & s) {
printf("\"");
for (sal_Int32 i = 0; i < s.getLength(); ++i) {
sal_Unicode c = s[i];
if (c == '"' || c == '\\') {
printf("\\%c", static_cast< char >(c));
} else if (s[i] >= ' ' && s[i] <= '~') {
printf("%c", static_cast< char >(c));
} else {
printf("\\u%04X", static_cast< unsigned int >(c));
}
}
printf("\"");
}
</source>
If you want to see the content of an OUString with standard output, you have only to convert it in OString :
<source lang="cpp">
//Listing 11-c Printing out an OUString with standard C++ output
// C++
OUString OUStr = OUString::createFromAscii( "Hello" );
OString OStr = OUStringToOString ( OUStr,RTL_TEXTENCODING_UTF8);
cout << Ostr << endl;
</source>

===File Path ===

{{Documentation/Linux|Linux related content : the file paths are OS-dependent. To remove this dependency, UNO use URL and a way to transform a file path to an URL. We show an example now

<source lang="cpp">
// Listing 12 UNO URL
// C++
// Don't forget #include <osl/file.hxx>
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/edt.sxd"),sDocUrl);
// Windows C++ to check
// osl::FileBase::getFileURLFromSystemPath(
// OUString::createFromAscii("\"C:\\My Documents\\tata.sxc\""),sDocUrl);

</source>

A complete example is given in the below listing :

<source lang="cpp">
// Listing 13 Using URL
// C++
#include <stdio.h>
#include <cppuhelper/bootstrap.hxx>
#include <osl/file.hxx>
using rtl::OUString;
using rtl::OString;
using namespace osl;

main( ) {
OUString sDocUrl;
OString toPrintOut;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/edt.sxd"),sDocUrl);
toPrintOut = OUStringToOString( sDocUrl, RTL_TEXTENCODING_ASCII_US );
printf( "URL is : %s\n", toPrintOut.pData->buffer );
// prints out URL is : file:///home/smoutou/edt.sxd
return 0;
}
</source>

which shows how to use the conversion. Remember that we work with UNO and therefore the URL is an OUString.
}}

{{Documentation/Windows|Only file paths have to be changed to transform these programs into Windows programs}}

=== SDK Example ===
Here is some code provided by SDK :

<source lang="cpp">
// Listing 14 SDK Example
// C++
#include <stdio.h>
#include <rtl/ustrbuf.hxx>
#include <rtl/string.hxx>

using rtl::OUString;
using rtl::OUStringBuffer;
using rtl::OString;

int main( int argc, char * argv [] )
{
// string concatination

sal_Int32 n = 42;
double pi = 3.14159;

// give it an initial size, should be a good guess.
// stringbuffer extends if necessary
OUStringBuffer buf( 128 );

// append an ascii string
buf.appendAscii( "pi ( here " );

// numbers can be simply appended
buf.append( pi );

// lets the compiler count the stringlength, so this is more efficient than
// the above appendAscii call, where length of the string must be calculated at
// runtime
buf.appendAscii( RTL_CONSTASCII_STRINGPARAM(" ) multiplied with " ) );
buf.append( n );
buf.appendAscii( RTL_CONSTASCII_STRINGPARAM(" gives ") );
buf.append( (double)( n * pi ) );
buf.appendAscii( RTL_CONSTASCII_STRINGPARAM( "." ) );

// now transfer the buffer into the string.
// afterwards buffer is empty and may be reused again !
OUString string = buf.makeStringAndClear();

// I could of course also used the OStringBuffer directly
OString oString = rtl::OUStringToOString( string , RTL_TEXTENCODING_ASCII_US );

// just to print something
printf( "%s\n" ,oString.getStr() );
return 0;
}
</source>
This example shows an other way to use OUString, OString and buffer.

For performance analysis see
[http://udk.openoffice.org/common/man/concept/string_invest.html Some String Performance Thoughts]

===Sequence of Strings===
Sequence has been tackled in a previous [[SDKCppLanguage#Sequences|section]]. If you want to construct a Sequence of string (useful in list box ...) have a look on this piece of code :

<source lang="cpp">
// Listing 15 An Example of Sequence of Strings
// C++
// Sequence of string
#include <rtl/string.hxx>
// Don't forget to add #include <com/sun/star/uno/Sequence.hxx>
// Don't forget to add using namespace com::sun::star::uno;
Sequence<OUString>seqStrlistItems(2);
seqStrlistItems[0]=OUString::createFromAscii("Item1");
seqStrlistItems[1]=OUString::createFromAscii("Item2");

// retrieve them and prints out
for (int i=0;i<seqStrlistItems.getLength();i++){
OString toPrintOut = OUStringToOString(seqStrlistItems[i],RTL_TEXTENCODING_ASCII_US);
printf("-- %s\n",toPrintOut.pData->buffer);
}
</source>
This code prints out in the shell console :
<pre>
-- Item1
-- Item2
[smoutou@p3 Lifetime]$
</pre>

It is easy to understand and therefore I have nothing more to say about it.

===Exercise on Sequence of Strings===
Write and test the following "convert2SeqOUStrInDEBUGMODE" function with a sequence of "sal_Int8" as parameter and which returns a sequence of Strings in a format like the dump method of the old "debug" of DOS. This format [[UNO_registery_and_Bootstrapping#C.2B.2B_Code_to_recover_Information_in_a_Binary_Sequence|will be used here]], but without this function.

'''Solution''' : here is the corresponng function code
<source lang="cpp">
Sequence< OUString > convert2SeqOUStrInDEBUGMODE(Sequence < sal_Int8 > seqBytes){
sal_Int8 Hexa[16]={'0','1','2','3','4','5','6','7','8','9','A','B','C','D','E','F'};
sal_Int32 lin,col;
sal_Char line[80];
sal_Int32 len,sequenceSize,index;
len=seqBytes.getLength();
sequenceSize=(len>>4)+2;
if ((len&0XFFF0)==len) sequenceSize--; //if len%16==0
Sequence< OUString > SeqOUStr(sequenceSize);
// First line with length
SeqOUStr[0] = OUString::createFromAscii("Length:")+
OUString::valueOf((sal_Int32) seqBytes.getLength());
len = len&0XFFF0; // remove the modulo 16
for(lin=0;lin<len;lin=lin+16){
for(col=0;col<16;col++){
line[3*col]=Hexa[((unsigned char)seqBytes[lin+col])>>4];
line[3*col+1]=Hexa[seqBytes[lin+col]&0x0F];
line[3*col+2]=' ';
if ((seqBytes[lin+col]<128)&&(seqBytes[lin+col]>20)) line[50+col]=seqBytes[lin+col];
else line[50+col]='.';
} /* end of for */
line[66]=0; /* end of cstring...*/
line[48]=' ';line[49]=' ';
// ready to add the OUString in Sequence
if ((lin%16)==0) index = lin/16+1; else index=lin/16+2;
SeqOUStr[index]=OUString::createFromAscii(line);
} /* end of for */
// the last line is more complicated because not complete
// we only keep modulo
len=seqBytes.getLength()&0x000F;
if (len>0) { // only a line here if non-empty
for (lin=0;lin<len;lin++){
col=lin;
line[3*col]=Hexa[((unsigned char)seqBytes[lin])>>4];
line[3*col+1]=Hexa[seqBytes[lin]&0x0F];
line[3*col+2]=' ';
if ((seqBytes[lin]<128)&&(seqBytes[lin]>20)) line[50+col]=seqBytes[lin];
else line[50+col]='.';
}
// we complete the line
for (++col;col<16;col++){
line[3*col]=' ';line[3*col+1]=' ';line[3*col+2]=' ';line[50+col]=' ';
}
line[66]=0; /* end of string...*/
line[48]=' ';line[49]=' ';
// ready to add the OUString in Sequence
SeqOUStr[lin/16+2]=OUString::createFromAscii(line);
} //end if
return SeqOUStr;
}
</source>
and now how this function can be used :
<source lang="cpp">
sal_Int8 sourceArray[32]={1,22,23,24,55,56,57,8,9,10,11,12,13,14,15,16,17,18,19,61,62,-32,-33,-34,-35,26,127,-31,29,56,23,67};
Sequence < sal_Int8 > seqBytes(sourceArray,32);
Sequence < OUString > seqOUStr=convert2SeqOUStrInDEBUGMODE(seqBytes);
printf("%s\n",OUStringToOString( seqOUStr[0], RTL_TEXTENCODING_ASCII_US ).pData->buffer);
printf("%s\n",OUStringToOString( seqOUStr[1], RTL_TEXTENCODING_ASCII_US ).pData->buffer);
printf("%s\n",OUStringToOString( seqOUStr[2], RTL_TEXTENCODING_ASCII_US ).pData->buffer);
</source>
In our [[Constructing_Helpers#Reflection_Helper|introspection tool]] we need also this format but in one string. It's easy to write the corresponding code :
<source lang="cpp">
OUString convert2OUStrInDEBUGMODE(Sequence < sal_Int8 > seqBytes){
Sequence <OUString> SeqOUStr = convert2SeqOUStrInDEBUGMODE(seqBytes);
OUString OUStr;
for(sal_Int32 i=0;i<SeqOUStr.getLength();i++)
OUStr = OUStr+SeqOUStr[i]+OUString::createFromAscii("\n");
return OUStr;
}
</source>
which can be used with :
<source lang="cpp">
sal_Int8 sourceArray[32]={1,22,23,24,55,56,57,8,9,10,11,12,13,14,15,16,17,18,19,61,62,-32,-33,-34,-35,26,127,-31,29,56,23,67};
Sequence < sal_Int8 > seqBytes(sourceArray,32);

OUString OUStr=convert2OUStrInDEBUGMODE(seqBytes);
printf("%s\n",OUStringToOString( OUStr, RTL_TEXTENCODING_ASCII_US ).pData->buffer);
</source>

== [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno#Any|Any]] ==
We can find also good materials in Developer's guide on [[Documentation/DevGuide/FirstSteps/Any|Any type]]. [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno#Any|Any]] is easy to use only with <<= and >>= operators and we then often use intermediate variables. We can use also the build-in “makeAny” function :
<source lang="cpp">
// Listing 16 makeAny Example
// C++
Any any = makeAny((long) 1000);
</source>

We give first an example above :

<source lang="cpp">]
//Listing 17 Any Example
// C++
#include <stdio.h>
#include <cppuhelper/bootstrap.hxx>
#include <com/sun/star/uno/Any.hxx>
#include <com/sun/star/uno/Sequence.hxx>
using rtl::OUString;
using rtl::OString;
using com::sun::star::uno::Any;
using namespace com::sun::star::uno;
using namespace rtl;

main( ) {
Any any,any2;
sal_Int32 n=5,n2=18;
any <<= n;
// Gets the type name of the set value
OUString OUStr = any.getValueTypeName();
OString OStr = OUStringToOString( OUStr, RTL_TEXTENCODING_ASCII_US );
printf( "Any type : %s\n", OStr.pData->buffer );// prints out Any type : long
// Tests if any contains a value
if (any.hasValue()) printf("Any has a value\n");// prints out Any has a value
// Clears this any. If the any already contains a value, that value will be destructed and
// its memory freed. After this has been called, the any does not contain a value.
any.clear();
if (any.hasValue()) printf("Any has a value\n");// prints out nothing
any <<= n2;
any2 <<= OUStr;
// Unequality operator: compares two anys. The values need not be of equal type,
// e.g. a short integer is compared to a long integer
if (any != any2) printf("Two different any\n");

Sequence< Any> aValues(2);
aValues[0] <<= (float) 1.1; aValues[1] <<= OUString::createFromAscii("Text");
aValues[1] >>= OUStr;
OStr = OUStringToOString( OUStr, RTL_TEXTENCODING_ASCII_US );
float real;
aValues[0] >>= real;
printf("Seq - length : %d val : %f val %s\n",aValues.getLength(),real,OStr.pData->buffer);
return 0;
}
</source>

This program prints out :
<pre>
Any type : long
Any has a value
Two different any
Seq - length : 2 val : 1.100000 val Text
</pre>
Another important problem is a sequence of sequence of Any : we give now a piece of code without explanation :

<source lang="cpp">
// Listing 18 Sequence of Sequence of Any
// C++
Sequence< Sequence< Any > > aValues(2);
Sequence< Any > aValues2(2);
aValues2[0] <<= (double) 1.1; aValues2[1] <<= OUString::createFromAscii("Hello");
aValues[0] = aValues2;
aValues2[0] <<= (double)2.2; aValues2[1] <<= OUString::createFromAscii("Hi");
aValues[1] = aValues2;
</source>
This code uses two sequences. I have not found an other simpler way to do that. If anybody has a more straightforward solution, I would be happy learn about it.
If it is possible to access directely a value in a 2D array but I found only one means using an intermediate sequence (avalues2) in the case of sequence of sequence.

== Files ==

{{Documentation/Linux|

We want now create a text file named "demo.txt". Here is the code to do this :

<source lang="cpp">
// Listing 19 A little Example manipulating Files
// C++
#include <stdio.h>
#include <cppuhelper/bootstrap.hxx>
#include <osl/file.hxx>

using rtl::OUString;
using rtl::OString;
using namespace osl;

main( ) {
OUString FileName;
sal_Int8 tab[25]="Hi every body\n";
sal_uInt64 nb;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/demo.txt"),FileName);
File myfile(FileName);
myfile.open(OpenFlag_Write);
myfile.write(tab,(sal_uInt64)16,nb);
printf("%d bytes are written\n",nb);
myfile.close();
return 0;
}
</source>
}}
{{Documentation/Note|The method open is not described in C++ documentation !!! I have found it while reading the “file.hxx” header file.}}

The flag you can pass to the "open" method are : OpenFlag_Write, OpenFlag_Read, OpenFlag_Create. The " using namespace osl;" is obligatory even if the compiler doesn't complain without.
When a file is open, you can use the methods above :
<source lang="cpp">
// C++
// Write a number of bytes to a file
write( const void * pBuffer, sal_uInt64 uBytesToWrite, sal_uInt64 & rBytesWritten );

// Read a number of bytes from a file
read( void * pBuffer, sal_uInt64 uBytesRequested, sal_uInt64 & rBytesRead );

// Read a line from a file
ReadLine( ::rtl::ByteSequence & aSeq );

// Test if the end of a file is reached
isEndOfFile( sal_Bool * pIsEOF );

// Retrieve the current position of the internal pointer of an open file
getPos( sal_uInt64 & uPos );

// Set the internal position pointer of an open file.
setPos( sal_uInt32 uHow, sal_Int64 uPos );
</source>
There are other possibilities : move, remove, copy... See the documentation or read the file.hxx file.

See [http://udk.openoffice.org/common/man/concept/streams.html « Streaming interfaces »]
for an other way to use files.

== Threads ==

It would be great to use the Thread Class but it's so badly documented that we begin with process instead thread.
Starting from an example posted in the forum Working with a Spreadsheet Document in C++ (by lirincy). This example gives a working code to start OOo if not started when launching a binary executable. We remove what was not usefull for us and give two examples.
{{Documentation/Linux|
<source lang="cpp">
// Listing 20 A Process Example
// C++
#include <stdio.h>
#include <cppuhelper/bootstrap.hxx>
#include <osl/process.h>
#include <osl/file.hxx>

using rtl::OUString;
using rtl::OString;

main( ) {
// Don't forget to add #include <osl/process.h>
oslProcess hProcess = NULL;
// Don't forget to add #include <osl/file.hxx>
OUString FileURL;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/demo"),
FileURL
);
oslProcessError osl_error = osl_executeProcess(
FileURL.pData,
NULL,
0,
osl_Process_DETACHED,
0, /* osl_getCurrentSecurity() */
NULL,
NULL,
0,
&hProcess );
osl_error = osl_joinProcess(hProcess);
return 0;
}
</source>
}}
{{Documentation/Note|Note that the demo file is an existing binary in /home/smoutou.}}
If you want to pass something to the launched program see AppArgs variable in the second example :
{{Documentation/Linux|
<source lang="cpp">
// Listing 21 A second Process Example
// C++
#include <stdio.h>
#include <cppuhelper/bootstrap.hxx>
#include <osl/process.h>
#include <osl/file.hxx>

using rtl::OUString;
using rtl::OString;

main( ) {
// Don't forget to add #include <osl/process.h>
oslProcess hProcess = NULL;
// Don't forget to add #include <osl/file.hxx>
OUString FileURL;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/demo"),
FileURL
);
OUString AppArgs = OUString::createFromAscii("Arg1");
oslProcessError osl_error = osl_executeProcess(
FileURL.pData,
&AppArgs.pData,
1,
osl_Process_DETACHED,
0, /* osl_getCurrentSecurity() */
NULL,
NULL,
0,
&hProcess );
osl_error = osl_joinProcess(hProcess);

return 0;
}
</source>
}}
I have tried working with thread but only with C style at the moment (not with using the thread class). Here is my first example code :
{{Documentation/Linux|
<source lang="cpp">
// Listing 22 A working Thread Example
// C++
#include <stdio.h>
#include <cppuhelper/bootstrap.hxx>
#include <osl/thread.h>
#include <unistd.h> // LINUX

using rtl::OUString;
using rtl::OString;

/** wait _nSec seconds.
*/
void thread_sleep( sal_Int32 _nSec )
{
/// print statement in thread process must use fflush() to force display.
printf("# wait %d seconds. ", _nSec );
fflush( stdout );
sleep( _nSec );
printf("# done\n" );
}

void SAL_CALL thread1(void *) {
while(1)
printf("\n thread running");

}

void SAL_CALL thread2(int *nb){
while(1)
printf("\n thread nb=%d running",*nb);
}

main( ) {
// Don't forget to add #include <osl/thread.h>
oslThread hThread = NULL;
//oslWorkerFunction type : void (SAL_CALL *oslWorkerFunction)(void*); in osl/thread.h
oslWorkerFunction pFunction = (void (SAL_CALL *)(void*)) thread2;
int pthreaddata=2;
// create and start the thread2 with 2 as a parameter value
oslThread hThread2 = osl_createThread(pFunction,(void *) &pthreaddata);
// create and start the thread1
hThread = osl_createThread(thread1,NULL);

thread_sleep(2);
osl_suspendThread(hThread);
osl_suspendThread(hThread2);

return 0;
}
</source>
}}
What is printed out is depending on how screen is managed by your OS. Under Linux I obtained something like :
<pre>
...
thread running
thread running
thread running
thread running# done

thread nb=2 running
thread nb=2 running
thread nb=2 running
thread nb=2 running
....
</pre>
Here you can see the second thread launched writes at first and only when the main sleeping is terminated thread two is writing out. The other thread primitives can be found in osl/thread.h :
<pre>
/** Create the thread, using the function-ptr pWorker as
its main (worker) function. This functions receives in
its void* parameter the value supplied by pThreadData.
Once the OS-structures are initialized,the thread starts
running.
@return 0 if creation failed, otherwise a handle to the thread
*/
oslThread SAL_CALL osl_createThread(oslWorkerFunction pWorker, void* pThreadData);

/** Create the thread, using the function-ptr pWorker as
its main (worker) function. This functions receives in
its void* parameter the value supplied by pThreadData.
The thread will be created, but it won't start running.
To wake-up the thread, use resume().
@return 0 if creation failed, otherwise a handle to the thread
*/
oslThread SAL_CALL osl_createSuspendedThread(oslWorkerFunction pWorker, void* pThreadData);

/** Release the thread handle.
If Thread is NULL, the function won't do anything.
Note that we do not interfere with the actual running of
the thread, we just free up the memory needed by the handle.
*/
void SAL_CALL osl_destroyThread(oslThread Thread);

/** Wake-up a thread that was suspended with suspend() or
createSuspended(). The oslThread must be valid!
*/
void SAL_CALL osl_resumeThread(oslThread Thread);

/** Suspend the execution of the thread. If you want the thread
to continue, call resume(). The oslThread must be valid!
*/
void SAL_CALL osl_suspendThread(oslThread Thread);
/** Returns True if the thread was created and has not terminated yet.
Note that according to this definition a "running" thread might be
suspended! Also returns False is Thread is NULL.
*/
sal_Bool SAL_CALL osl_isThreadRunning(const oslThread Thread);

/** Blocks the calling thread until Thread has terminated.
Returns immediately if Thread is NULL.
*/
void SAL_CALL osl_joinWithThread(oslThread Thread);

/** Blocks the calling thread at least for the given number
of time.
*/
void SAL_CALL osl_waitThread(const TimeValue* pDelay);
</pre>

For more information you can read [[Uno/Article/Multi-Thread_Programming|Multi-Thread Programming]].

== To go further : the Enumeration Type Problem ==
Sometimes we will encounter enumeration values. We have to learn how to resolve the problem. An example will be discussed later but we give it without its context here. The Cell content in OOoCalc is described by an enumeration. How can I know that, is not easy with the previous material, but I want to tackle the problem even if too soon to understand for a first reading.

All types used in programming are described in IDL files. Sometimes these IDL files are used to create hpp/hxx files.

This example is around CellContentType.idl file. Here is the summary of this file where we remove comments :

<source lang="idl">
// Listing 23 CellContentType Enumeration type (IDL File)
// IDL
namespace com{
namespace sun{
namespace star{
namespace table{
enum CellContentType
{
CellContentType_EMPTY = 0,
CellContentType_VALUE = 1,
CellContentType_TEXT = 2,
CellContentType_FORMULA = 3,
CellContentType_MAKE_FIXED_SIZE = SAL_MAX_ENUM
};
} // table
} // star
} // sun
} // com
</source>
Three tips can be used when using this kind of enumeration :
* In C++ a corresponding using namespace is necessary
using namespace com::sun::star::table
This line can be drawn from the IDL file.
* In C++ an include directive is necessary
<source lang="cpp">
#include <com/sun/star/table/CellContentType.hpp>
</source>
The name of the file to include and the path is easy to draw from IDL file.
* We have to construct the previous hpp file. This is done with adding the red line above in the makefile :
<pre>
TYPES := \
com.sun.star.uno.XNamingService \
com.sun.star.uno.XComponentContext \
com.sun.star.uno.XWeak \
com.sun.star.uno.XAggregation \
com.sun.star.lang.XMain \
com.sun.star.lang.XMultiServiceFactory \
com.sun.star.lang.XSingleComponentFactory \
com.sun.star.lang.XTypeProvider \
com.sun.star.lang.XComponent \
com.sun.star.registry.XSimpleRegistry \
com.sun.star.registry.XImplementationRegistration \
com.sun.star.bridge.XBridgeFactory \
com.sun.star.bridge.XUnoUrlResolver \
com.sun.star.table.CellContentType \
com.sun.star.container.XHierarchicalNameAccess
</pre>
After you can use this enumeration without problem like this :
<source lang="cpp">
// Listing 24 Enumeration type : an Example
//C++
// To check
// Don't forget to add #include <com/sun/star/table/CellContentType.hpp>
// Don't forget to add "com.sun.star.table.CellContentType \" in the makefile

using namespace com::sun::star::table
short enumval;
enumval = CellContentType_EMPTY;
switch (enumval){
case CellContentType_EMPTY : printf("Empty\n");break;
case CellContentType_VALUE : printf("Numerical Value\n");break;
case CellContentType_TEXT : printf("Text\n");break;
case CellContentType_FORMULA : printf("Formula\n");break;
}
</source>
What is shown here is a general SDK's feature : we construct a hpp file starting from an IDL file. This is so important and unexpected for beginners that I will repeat many times these explanations [[UNO_automation_with_a_binary_%28executable%29#Introduction_to_Bootstrapping|later]] and more deeply [[IDL_Files_and_Cpp#Getting_an_interface_in_C.2B.2B|here]].

== To go further : the Constant Type Problem ==
Values are not always defined with enumeration types as shown in previous section. Sometimes constants are used when programming with UNO. One example is again tackled [[OpenOffice_Calc#The_Compute_Function__Example|later]] but we want again writes on it now. We first present the corresponding IDL file (as an example)

<source lang="idl">
// Listing 25 CellFlags Constants type : IDL File
//IDL
module com { module sun { module star { module sheet {
constants CellFlags
{
const long VALUE = 1;
const long DATETIME = 2;
const long STRING = 4;
const long ANNOTATION = 8;
const long FORMULA = 16;
const long HARDATTR = 32;
const long STYLES = 64;
const long OBJECTS = 128;
const long EDITATTR = 256;
};
}; }; }; };
</source>
Compare this listing with Listing 23 to see the differences.
If you want to use the constants above you first generate the corresponding hpp file with modifying the makefile as in previous section, and then add the corresponding include directive :
<source lang="cpp">
// C++
#include <com/sun/star/sheet/CellFlags.hpp>
</source>
in your C++ code. Note that with this include directive you can directly write something like
<source lang="cpp">
// C++
VALUE | DATETIME
</source>
instead of
<source lang="cpp">
// C++
CellFlags_VALUE | CellFlags_DATETIME
</source>
as seen previously.

==Going further with Sequences==
We want to give any utilities used later in this document.
===Converting Sequences into Array===
Because it exists a correponding member function this conversion is very easy :
<source lang="cpp">
//Listing 27 Conversion Example
// C++
Sequence < sal_Int32 > SetOfInt(5);
sal_Int32 *table;
table = SetOfInt.getArray();
</source>
If you read carefully to this point, this code is familiar for you : it's drawn from Listing 4 and then already explained.
===Converting Sequence of Sequence into Array===
This problem has to be solved. We will use this kind of conversion later (see chapter 14). We first give two subprograms, to print out and to convert :
<source lang="cpp">
//Listing 28 Sequence of Sequence into 1D array
//C+
// Sequence of Sequence is printed out like that :
// toPrint[0][0] toPrint[0][1] toPrint[0][2]...
// toPrint[1][0] toPrint[1][1] toPrint[1][2]...
// ...
// Note that i denotes the first index
void printOutSeqSeq(const Sequence < Sequence < double > > &toPrint){
cout << "Prints out SeqSeq" << endl;
for(int i=0;i<toPrint.getLength();i++){
Sequence < double > rLine = toPrint[i];
double *line= rLine.getArray();
for(int j=0;j<rLine.getLength();j++)
cout << " " << line[j] << " ";
cout << endl;
}
}

double *SeqSeqToArray1D(const Sequence < Sequence < double> > &seqseq){
sal_Int32 iMax=seqseq.getLength(),jMax;
Sequence < double > rLine = seqseq[0];
jMax=rLine.getLength();
double *table1D = new double[iMax*jMax];
for (sal_Int32 i = 0 ; i < iMax; i++ )
for(sal_Int32 j = 0 ; j < jMax; j++ )
table1D[i*jMax+j]= seqseq[i][j];
return table1D;
}
</source>
Using these sub is easy : it can be done like that :
<source lang="cpp">
//Listing 29 Using the conversion
//C+
// We first construct a sequence
Sequence < double > demo(5);
demo[0]=1.1;
demo[1]=2.1;
demo[2]=3.1;
demo[3]=4.1;
demo[4]=5.1;
// We then construct the sequence of sequence
Sequence < Sequence < double > > seqseq(3);
for (int i=0; i<seqseq.getLength();i++)
seqseq[i]=demo;
// We print out the result of the construction
printOutSeqSeq(seqseq);
// Here is the conversion
double *table = SeqSeqToArray1D(seqseq);
// We finish wit printing out the result
cout << "Array1D -> 2D : "<< endl;
for (int i=0; i< 3; i++){
for (int j=0;j<5;j++)
cout<<" "<<table[i*5+j]<<" ";
cout<<endl;
}
....
delete table;
</source>
which gives us :
<pre>
Prints out SeqSeq
1.1 2.1 3.1 4.1 5.1
1.1 2.1 3.1 4.1 5.1
1.1 2.1 3.1 4.1 5.1
Array1D -> 2D :
1.1 2.1 3.1 4.1 5.1
1.1 2.1 3.1 4.1 5.1
1.1 2.1 3.1 4.1 5.1
[smoutou@p3 Lifetime]$
</pre>
Converting a sequence of sequence directly in an 2D array is not an easy task because the compiler has to know the size of the second index before compiling. At first something like
<source lang="cpp">
//Listing 30 Array2D conversion
// C++
double **SeqSeqToArray2D(const Sequence < Sequence < double> > &seqseq){
double **table2D;
double *table1D;
table1D = SeqSeqToArray1D(seqseq);
table2D = &table1D;
return table2D;
}
</source>
seems interesting but let's see if that works out. A first idea is to write something like :
<source lang="cpp">
//Listing 31 Wrong code for conversion
// C++
double **table2= SeqSeqToArray2D(seqseq);
for (int i=0; i< 3; i++){
for (int j=0;j<5;j++)
cout<<" "<< table2[i][j]<<" ";
cout<<endl;
}
delete table2;
</source>
but the compiler is unable to calculate table2[i][j] here. For that it has to evaluate the expression i*jMax+j but has no knowledge on jMax !!

===More Abstractions with STL===
If you plan to use C++ you will certainly use the STL extensively. We begin first by conversions. Here is the easier one :
<source lang="cpp">
//Listing 32 Converting a Sequence of Sequence into a vector
// C++
// Inspired by Eric Ehlers's code but using template
// See chapter 14
template< typename T>
vector < T >SeqSeqToVectorTemplate(const Sequence< Sequence < T > >& ss) {
vector < T >v;
for (int i=0; i<ss.getLength(); i++)
for (int j=0; j<ss[i].getLength(); j++)
v.push_back(ss[i][j]);
return v;
}
</source>
My start point for achieving this code was Eric Ethler's code presented [[CompleteAddIn#Transforming_an_Array_into_Sequence_of_Sequence|here]]. This code is again easy to use :
<source lang="cpp">
//Listing 33 Using the previous Convertion
// C++
#include <iostream>
#include<vector>
#include <cppuhelper/bootstrap.hxx>
#include <com/sun/star/uno/Sequence.hxx>
using namespace com::sun::star::uno;
using namespace std;

template< typename T>
vector < T >SeqSeqToVectorTemplate(const Sequence< Sequence < T > >& ss);
main( ) {
Sequence < double > demo(5);
demo[0]=1.1;
demo[1]=2.1;
demo[2]=3.1;
demo[3]=4.1;
demo[4]=5.1;
Sequence < Sequence < double > > seqseq(3);
// simply use the same sequence
for (int i=0; i<seqseq.getLength();i++)
seqseq[i]=demo;
// template
vector <double> v=SeqSeqToVectorTemplate(seqseq);
cout << "vector1D -> 2D : "<< endl;
for (int i=0; i< 3; i++){
for (int j=0;j<5;j++)
cout<<" "<<v[i*5+j]<<" ";
cout<<endl;
}
return 0;
}
</source>
We give now three other conversions (see also [[CompleteAddIn#Transforming_an_Array_into_Sequence_of_Sequence|here]])
<source lang="cpp">
//Listing 34 Converting Utilities with Template
// C++
// Inspired by Eric Ethler's code but using template
// See chapter 14
template< typename T>
Sequence< Sequence< T > > VectorTemplateToSeqSeq(const vector < T > &v) {
Sequence< Sequence< double > > ss(v.size());
for (unsigned int i=0; i<v.size(); i++) {
Sequence< T > s(1);
s[0] = v[i];
ss[i] = s;
}
return ss;
}
template< typename T>
vector < vector < T > >SeqSeqToMatrixTemplate(const Sequence< Sequence < T > >& ss) {
vector < vector < T > >vv;
for (int i=0; i<ss.getLength(); i++) {
vector < T >v;
for (int j=0; j<ss[i].getLength(); j++)
v.push_back(ss[i][j]);
vv.push_back(v);
}
return vv;
}
template< typename T>
Sequence< Sequence< T > > MatrixTemplateToSeqSeq(
const std::vector < std::vector < T > >&vv) {
Sequence< Sequence< T > > ss(vv.size());
for (unsigned int i=0; i<vv.size(); i++) {
std::vector < T > v = vv[i];
Sequence< T > s(v.size());
for (unsigned int j=0; j<v.size(); j++)
s[j] = v[j];
ss[i] = s;
}
return ss;
}
</source>
One way to use it is for instance :
<source lang="cpp">
//Listing 35 Converting Utilities with Template
//C++
...
// seqseq must be initialized
vector <vector <double> > v2=SeqSeqToMatrixTemplate(seqseq);
cout << "vector2D : "<< endl;
for (int i=0; i< 3; i++){
for (int j=0;j<5;j++)
cout<<" "<<v2[i][j]<<" ";
cout<<endl;
}
</source>
Because there is a lot of algorithms based on STL I think these utilities will be very helpfull.

{{Template:Home_Page}}

= See also =
* [[FR/Documentation/Cpp_Guide|French version of this chapter]].
* [[Uno/Article/Understanding_Uno|Understanding Uno]]
* [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno|C++ and UNO tutorial]]
* [[Uno/Article/Multi-Thread Programming | Multi-Thread Programming]]
* To learn C++ : [http://www.smart2help.com/e-books/ C++ e-books]
* [http://en.wikibooks.org/wiki/Programming:Data_Structures Wiki on C++ Data Structures]
* [[Uno/Binary/Analysis/String_Performance|String Performance]]
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal

[[Category:Tutorial]]
[[Category:Cpp]]
[[Category:Uno]]

SDKCppLanguage

2014-07-11T00:51:28Z

Global667: /* Our starting Example : Simple Binaries (Executable) */ update text and source

{{Documentation/Banner}}
{{Documentation/NeedsRework}}
=The UNO C++ Language=
The aim of this chapter is to explain peculiarities of the C++ language in the UNO environment and not to provide skills on traditional C++. To put it differently, I want to give here the UNO/C++ background, quite helpful in getting us started.
You can find e-Books on C++ [http://www.smart2help.com/e-books/ here].

See also [[Uno/Article/Understanding_Uno|Understanding Uno]], [[Documentation/DevGuide/FirstSteps/Objects%2C_Interfaces%2C_and_Services|Objects, Interfaces, and Services]] and [[Documentation/BASIC_Guide/UNO|OOoBasic UNO Guide]] for a start with UNO.

== Our starting Example : Simple Binaries (Executable) ==

We want now to start with a SDK example. The purpose of the example presented is to create an executable which interacts with OpenOffice.org. We can imagine two kind of interactions : direct interaction with OpenOffice.org or interaction with one of OOo's shared library. We focus on this second case where the makefile is simpler. The shared library involved is then cppuhelper.uno.so (cppuhelper.uno.dll under Windows). Former case will be examined later.
I assume (I know nobody of the SDK team) this example is given to provide the simplest example we can do with the SDK. This is the Lifetime example: see at “<SDK_Folder>/examples/DevelopersGuide/ProfUNO/Lifetime”

Before diving into the examples, you will need to set up your programming environment so you can create UNO programs. What's required depends on what platform you're working. This is shown in the first example with LINUX platform.
To check this example you only have to launch the makefile :
{{Documentation/Linux|
<pre>
cd <SDK_Folder>
./setsdkenv_unix
cd examples/DevelopersGuide/ProfUNO/Lifetime
make
make ProfUnoLifetime.runexe
</pre>
}}
The last command line only launch the binary executable “ProfUnoLifetime” which interact with cpphelper.uno.so (cppuhelper.uno.dll under Windows) even if OpenOffice.org is not running.
This example creates and releases an object, nothing more. The constructor and destructor of the object only write out a message. Its little size allows us to give its code here:
<source lang="cpp">
// Listing 1 First Example (from SDK)
// C++
#include <stdio.h>#include <cppuhelper/weak.hxx>class MyOWeakObject : public ::cppu::OWeakObject{public: MyOWeakObject() { fprintf( stdout, "constructed\n" ); } ~MyOWeakObject() { fprintf( stdout, "destructed\n" ); }};void simple_object_creation_and_destruction(){ // create the UNO object com::sun::star::uno::XInterface * p = new MyOWeakObject(); // acquire it, refcount becomes one p->acquire(); fprintf( stdout, "before release\n" ); // release it, refcount drops to zero p->release(); fprintf( stdout, "after release\n" );}
int main( char * argv[] ){ simple_object_creation_and_destruction(); return 0;}
</source>

The two methods acquire and release will be encountered later. What exactly they do is not important for the moment. This example shows us how to write a class which inherits from an other class, how to write and call methods and how to instantiate the class.
All the listings given below only need to modify this C++ code compile it and run it. You can therefore use the same makefile by possibly changing the name of the source file (tackled in next section).

== Types ==
The [[Documentation/DevGuide/FirstSteps/Common_Types|UNO types]] are given in the table below :
; UNO Types
{| border cellspacing="0" width="550"
|- style = "background:#b3e2d1;text-align:center"
| |UNO||Type description||Java||C++||Basic
|- style="text-align:center"
| char||16-bit unicode character type||char||sal_Unicode || -
|- style="text-align:center"
|boolean ||boolean type; true and false ||boolean ||sal_Bool||Boolean
|- style="text-align:center"
|byte ||8-bit ordinal type||byte ||sal_Int8 ||Integer
|- style="text-align:center"
|short ||signed 16-bit ordinal type||short ||sal_Int16 ||Integer
|- style="text-align:center"
|unsigned short||unsigned 16-bit ordinal type||- ||sal_uInt16 ||-
|- style="text-align:center"
|long ||signed 32-bit ordinal type||int ||sal_Int32 ||Long
|- style="text-align:center"
|unsigned long ||unsigned 32-bit type ||- ||sal_uInt32 ||-
|- style="text-align:center"
|hyper||signed 64-bit ordinal type||long ||sal_Int64 ||-
|- style="text-align:center"
|unsigned hyper ||unsigned 64-bit ordinal type||- ||sal_uInt64 ||-
|- style="text-align:center"
|float ||processor dependent float||float ||float (IEEE float) ||Single
|- style="text-align:center"
|double ||processor dependent double||double||double (IEEE double)||Double
|}

The UNO's column represents all the types you can find in the specifications files : IDL files. We describe IDL files later (see chapter 10). The C++ column is what we are interested in when we program with this language. If you want to check the different programs given in this chapter, you can use the <OpenOffice.org1.1_SDK>/examples/DevelopersGuide/ProfUNO/Lifetime
example. Replace object_lifetime.cxx completely with the listing below (don't forget to save the old file)

<source lang="cpp">
// Listing 2 A short UNO Program
// C++
#include <stdio.h>
#include <cppuhelper/bootstrap.hxx>

main( ) {
sal_Int32 var1;
var1 = 34;
printf("The var1 value is : %d\n",var1);
return 0;
}
</source>

then launch
<pre>
make ALL
make ProfUnoLifetime.runexe
</pre>
and it works. Don't forget ./setsdkenv_unix (only one time) on Linux and the corresponding command (setsdkenv_windows.bat) on Windows.

==[[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno#Sequence|Sequences]]==
We can find also good materials in Developer's guide on [[Documentation/DevGuide/FirstSteps/Sequence|Sequence]].
A sequence is an abstract view of a set of UNO types with a variable number of elements. As first example, we give a very simple program:

<source lang="cpp">
// Listing 3 UNO Sequences
// C++
#include <stdio.h>
#include <cppuhelper/bootstrap.hxx>
#include <com/sun/star/uno/Sequence.hxx>
using namespace com::sun::star::uno;

main( ) {
Sequence < sal_Int32 > SetOfInt(5);
//var1 = 34;
SetOfInt[2]=44;
printf("The value is : %d\n",SetOfInt[2]);
return 0;
}
</source>

The important things to notice are as follows:
* the type of each element of the set is put between angular brackets: "<" and ">". In the example above sal_int32 is the type.
* declaration of sequence is done with parentheses "(" and ")" and the number of elements of the sequence between them. In the example above a sequence of five sal_Int32 elements is declared.
* accessing elements of the sequence is done with "[" and "]" and an index between them (generaly called subscript operator). This allows us to say that sequences are referenced like arrays. But they are different in some way, for instance they don't have a fixed size.
* We have to include Sequence.hxx file in a program when using Sequence. Note that this file is provided with the SDK and this not always the case for all hxx files (some of them have to be reconstructed).
We have to use the correct namespace with adding "using namespace ..." If you don't use this statement you have to write com::sun::star::uno::Sequence instead of Sequence.
A Sequence can be created with arbitrary UNO type but not with other types.
The object SetOfInt has many methods. We give an example to show some of them:
<source lang="cpp">
// Listing 4 Examples of using Sequence Methods
// C++
#include <stdio.h>
#include <cppuhelper/bootstrap.hxx>
#include <com/sun/star/uno/Sequence.hxx>
using namespace com::sun::star::uno;

main( ) {
Sequence < sal_Int32 > SetOfInt(5);
sal_Int32 *table;
SetOfInt[2]=44;
printf("The value is : %d\n",SetOfInt[2]);
// Tests whether the sequence has elements, i.e. elements count is greater than zero
if (SetOfInt.hasElements()) printf("Set not empty\n");
// Gets a pointer to elements array for reading and writing. If the sequence
// has a length of 0, then the returned pointer is undefined
table = SetOfInt.getArray();
table[4]=78;
printf("The value is : %d\n",SetOfInt[4]); // prints out 78
SetOfInt.realloc(7);
printf("New length : %d\n",SetOfInt.getLength()); // prints out 7
return 0;
}
</source>

The comments explain what is printed out when executing this example. The method realloc is particularly important: it allows the size of set to change.

Let us focus on using sequences in function or as parameter. An example is again more descriptive than a long text:

<source lang="cpp">
// Listing 5 Sequence and Parameters
// C++
// function
Sequence < sal_Int32 > initSequence(){
sal_Int32 sourceArray[5]={1,2,3,4,5};
Sequence < sal_Int32 > SeqOfInt(sourceArray,5);
return SeqOfInt;
}
// reference parameter
void initSequence2(Sequence < sal_Int32 > &SeqOfInt ) {
sal_Int32 sourceArray[4]={1,2,3,4};
Sequence < sal_Int32 > SeqOfInt2(sourceArray,4);
SeqOfInt=SeqOfInt2;
}
</source>
An obvious call could be :

<source lang="cpp">
// Listing 6 Sequence and Parameters (following)
// C++
SetOfInt = initSequence();
printf("New length : %d\n",SetOfInt.getLength()); // prints out 5
initSequence2(SetOfInt);
printf("New length : %d\n",SetOfInt.getLength()); // prints out 4
</source>
We cannot leave this section without adding that operators == and != are available with sequences. Note also that "toUnoSequence()", "getCppuSequenceType()" and "getCharSequenceCppuType()" are also member functions.

Passing a sequence into a function by value is, like a vector, somewhat inefficient because the function must make a copy of all elements. It's better to use a constant reference as shown below:
<source lang="cpp">
// Listing 7 The Constant Reference method
//C++
#include <iostream>
#include <cppuhelper/bootstrap.hxx>
#include <com/sun/star/uno/Sequence.hxx>
using namespace com::sun::star::uno;
using namespace std;

// Passing a Sequence by value using the Constant Reference method
void avoidCopy(const Sequence< double > &ConstRef){
// ConstRef[2]=6.7; would fail here
for(int i=0;i<ConstRef.getLength();i++)
cout<<ConstRef[i]<<" ";
cout<<endl;

}

main( ) {
Sequence < double > demo(5);
demo[0]=1.1;
demo[1]=2.1;
demo[2]=3.1;
demo[3]=4.1;
demo[4]=5.1;
avoidCopy(demo);
return 0;
}
</source>

See other material in Developer's Guide (UNO C++ Binding).

==Strings==

In C, a string is simply an array of characters that always includes a binary zero (often called the null terminator) as its final array element. UNO/C++ API manages strings with two classes: OUString and OString. The former uses Unicode characters.

; STRING UNO Type
{| border cellspacing="0" width="550"
|- style = "background:#b3e2d1;text-align:center"
| |UNO||Type description||Java||C++||Basic
|- style="text-align:center"
| string||String of 16-bit unicode characters ||Java.lang.string||::rtl::OUString || String
|}

But, if you want to use ASCII characters the latter class is for you.
===OUString and OString===
OUString and OString classes are designed for UNO programmers. Only OString can be used with a standard C printf. To put it differently OString is nearer to the common C ASCII strings (array of characters) than OUString (which is an array of Unicode).
But all strings managed by UNO API are OUString. That means, if you want to see something in the console, you have to convert OUString to OString. If you ask something to the user and want to pass it to UNO API, you have to convert OString to OUString. Then if you want to use the console (in general for testing) you have to learn first both conversions.

==== OUString to OString ====

If OUStr is a OUString object, we give this example for conversion:

<source lang="cpp">
// Listing 8 Converting OUString into OString
// C++
#include <rtl/string.hxx>

OString o = OUStringToOString( OUStr, RTL_TEXTENCODING_ASCII_US );
printf( "Conversion result : %s\n", o.pData->buffer );
</source>

==== OString to OUString ====
The inverse conversion is easy too :
<source lang="cpp">
// Listing 9 Converting OString into OUString
// C++
OUString foo;
foo = OUString::createFromAscii("Hi every body");
</source>

Here is a complete conversion example:

<source lang="cpp">
// Listing 10 A complete Example
// C++
#include <stdio.h>
#include <cppuhelper/bootstrap.hxx>
#include <rtl/string.hxx>
using namespace rtl;

main( ) {
OUString OUStr;
OUStr = OUString::createFromAscii("Hi every body");
OString OStr = OUStringToOString( OUStr, RTL_TEXTENCODING_ASCII_US );
printf( "OUStr was : %s\n", OStr.pData->buffer );
return 0;
}
</source>

We see that a rtl namespace has to be used. If not, please replace OUString by ::rtl::OUString.
OUString and OString objects are class type variables, and then the operations that can be performed on O(U)Strings take the form
<pre>
O(U)StringVariable.operation(argumentList)
</pre>
For example, if string1 and string2 are variables of type OUString, then
<pre>
string1.compareTo(string2)
</pre>
can be used to compare both strings. A function like compareTo(), which is part of the O(U)String-class is called a member function. The O(U)String class offers a large number of these member functions, as well as extensions of some well-known operators, like the assignment (=) and the comparison operator (==). These operators and functions are discussed in the following sections.
The OUString and OString methods are similar: we give a complete example which shows some of them:
<source lang="cpp">
// Listing 11 A more complete Example
// C++
#include <stdio.h>
#include <cppuhelper/bootstrap.hxx>
#include <rtl/string.hxx>
using rtl::OUString;
using rtl::OString;

main( ) {
OUString OUStr1,OUStr2;
OString OStr1, OStr2;
OStr1="Hi every body";
OStr2="every body";
OUStr1 = OUString::createFromAscii("Hi every body");
OUStr2 = OUString::createFromAscii("Hi every body");
// Returns the length of this string
printf("Length : %d\n",OUStr1.getLength()); // prints out 13
// Compares two strings
printf("CompareTo : %d\n",OUStr1.compareTo(OUStr2)); // prints out 0
// Compares two strings
// serviceName.equalsAsciiL( RTL_CONSTASCII_STRINGPARAM("my_module.MyService2") );
printf("equals : %d\n",OUStr1.equals(OUStr2)); // prints out 1
if (OUStr1.equals(OUStr2)) printf("OK\n");// prints out OK
// Compares two strings
printf("CompareToAscii : %d\n",OUStr1.compareToAscii(OStr1)); // prints out 0
// Compares two strings with a maximum count of characters
printf("CompareToAscii : %d\n",OUStr1.compareToAscii(OStr1),10); // prints out 0
// Perform a comparison of a substring in this string
// is "every body" in position 3 of OUStr1 ?
if (OUStr1.match(OUString::createFromAscii("every body"),3))
printf("match : OK\n"); //prints out match : OK
// Perform a comparison of a substring in this string
if (OUStr1.matchAsciiL(OStr2,OStr2.getLength(),3))
printf("matchAsciiL: OK\n");
// Returns the float value from this string
OUStr2 = OUString::createFromAscii("1.675");
printf("toFloat : %f\n",OUStr2.toFloat()); // prints out 1.675000
// Value Of :
OUStr1 = OUStr1.valueOf((float)1.56);
OStr1 = OUStringToOString( OUStr1, RTL_TEXTENCODING_ASCII_US );
printf( "Value of : %s\n", OStr1.pData->buffer );
// concat
OUStr2=OUStr2.concat(OUString::createFromAscii(" ..."));
OStr1 = OUStringToOString( OUStr2, RTL_TEXTENCODING_ASCII_US );
printf( "concat is : %s\n", OStr1.pData->buffer );
return 0;
}
</source>
We can also see in this program how the concat method (three last lines) is used. The toFloat() conversion method is not alone: toBoolean(), toChar(), toInt32(), toInt64() , toDouble(), toAsciiLowerCase() and toAsciiUpperCase() exist also. Now we terminate with presenting some other methods (see C++ material):

; String methods
{| border cellspacing="0" width="850"
|- style = "background:#b3e2d1;text-align:center"
| colspan="2"|Methods
|- style="text-align:center"
|indexOf( sal_Unicode ch, sal_Int32 fromIndex = 0 ) ||Returns the index within this string of the first occurrence of the specified character, starting the search at the specified index
|- style="text-align:center"
|sal_Int32 hashCode()||Returns a hashcode for this string
|- style="text-align:center"
|sal_int32 lastIndexOf(sal_Unicode ch )||Returns the index within this string of the last occurrence of the specified character, searching backward starting at the end
|- style="text-align:center"
|sal_Int32 lastIndexOf(sal_Unicode ch, sal_Int32 fromIndex ) ||Returns the index within this string of the last occurrence of the specified character, searching backward starting at the specified index
|- style="text-align:center"
|sal_Int32 lastIndexOf(const OUString & str ) || Returns the index within this string of the last occurrence of the specified substring, searching backward starting at the end
|- style="text-align:center"
|OUString copy(sal_Int32 beginIndex, sal_Int32 count ) OUString copy(sal_Int32 beginIndex ) ||Returns a new string that is a substring of this string
|- style="text-align:center"
|OUString replaceAt(sal_Int32 index, sal_Int32 count, const OUString & newStr ) ||Returns a new string resulting from replacing n = count characters from position index in this string with newStr
|- style="text-align:center"
|OUString replace(sal_Unicode oldChar, sal_Unicode newChar ) ||Returns a new string resulting from replacing all occurrences of oldChar in this string with newChar
|- style="text-align:center"
|OUString trim() ||Returns a new string resulting from removing white space from both ends of the string
|- style="text-align:center"
|OUString getToken(sal_Int32 token, sal_Unicode cTok, sal_Int32 & index ) ||Returns a token in the string
|}

I cannot close this section without giving a code found in OOo source /OOB680_m5/registry/source/regimpl.cxx
<source lang="cpp">
//Listing 11-b Printing out an OUString
// C++
void printString(rtl::OUString const & s) {
printf("\"");
for (sal_Int32 i = 0; i < s.getLength(); ++i) {
sal_Unicode c = s[i];
if (c == '"' || c == '\\') {
printf("\\%c", static_cast< char >(c));
} else if (s[i] >= ' ' && s[i] <= '~') {
printf("%c", static_cast< char >(c));
} else {
printf("\\u%04X", static_cast< unsigned int >(c));
}
}
printf("\"");
}
</source>
If you want to see the content of an OUString with standard output, you have only to convert it in OString :
<source lang="cpp">
//Listing 11-c Printing out an OUString with standard C++ output
// C++
OUString OUStr = OUString::createFromAscii( "Hello" );
OString OStr = OUStringToOString ( OUStr,RTL_TEXTENCODING_UTF8);
cout << Ostr << endl;
</source>

===File Path ===

{{Documentation/Linux|Linux related content : the file paths are OS-dependent. To remove this dependency, UNO use URL and a way to transform a file path to an URL. We show an example now

<source lang="cpp">
// Listing 12 UNO URL
// C++
// Don't forget #include <osl/file.hxx>
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/edt.sxd"),sDocUrl);
// Windows C++ to check
// osl::FileBase::getFileURLFromSystemPath(
// OUString::createFromAscii("\"C:\\My Documents\\tata.sxc\""),sDocUrl);

</source>

A complete example is given in the below listing :

<source lang="cpp">
// Listing 13 Using URL
// C++
#include <stdio.h>
#include <cppuhelper/bootstrap.hxx>
#include <osl/file.hxx>
using rtl::OUString;
using rtl::OString;
using namespace osl;

main( ) {
OUString sDocUrl;
OString toPrintOut;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/edt.sxd"),sDocUrl);
toPrintOut = OUStringToOString( sDocUrl, RTL_TEXTENCODING_ASCII_US );
printf( "URL is : %s\n", toPrintOut.pData->buffer );
// prints out URL is : file:///home/smoutou/edt.sxd
return 0;
}
</source>

which shows how to use the conversion. Remember that we work with UNO and therefore the URL is an OUString.
}}

{{Documentation/Windows|Only file paths have to be changed to transform these programs into Windows programs}}

=== SDK Example ===
Here is some code provided by SDK :

<source lang="cpp">
// Listing 14 SDK Example
// C++
#include <stdio.h>
#include <rtl/ustrbuf.hxx>
#include <rtl/string.hxx>

using rtl::OUString;
using rtl::OUStringBuffer;
using rtl::OString;

int main( int argc, char * argv [] )
{
// string concatination

sal_Int32 n = 42;
double pi = 3.14159;

// give it an initial size, should be a good guess.
// stringbuffer extends if necessary
OUStringBuffer buf( 128 );

// append an ascii string
buf.appendAscii( "pi ( here " );

// numbers can be simply appended
buf.append( pi );

// lets the compiler count the stringlength, so this is more efficient than
// the above appendAscii call, where length of the string must be calculated at
// runtime
buf.appendAscii( RTL_CONSTASCII_STRINGPARAM(" ) multiplied with " ) );
buf.append( n );
buf.appendAscii( RTL_CONSTASCII_STRINGPARAM(" gives ") );
buf.append( (double)( n * pi ) );
buf.appendAscii( RTL_CONSTASCII_STRINGPARAM( "." ) );

// now transfer the buffer into the string.
// afterwards buffer is empty and may be reused again !
OUString string = buf.makeStringAndClear();

// I could of course also used the OStringBuffer directly
OString oString = rtl::OUStringToOString( string , RTL_TEXTENCODING_ASCII_US );

// just to print something
printf( "%s\n" ,oString.getStr() );
return 0;
}
</source>
This example shows an other way to use OUString, OString and buffer.

For performance analysis see
[http://udk.openoffice.org/common/man/concept/string_invest.html Some String Performance Thoughts]

===Sequence of Strings===
Sequence has been tackled in a previous [[SDKCppLanguage#Sequences|section]]. If you want to construct a Sequence of string (useful in list box ...) have a look on this piece of code :

<source lang="cpp">
// Listing 15 An Example of Sequence of Strings
// C++
// Sequence of string
#include <rtl/string.hxx>
// Don't forget to add #include <com/sun/star/uno/Sequence.hxx>
// Don't forget to add using namespace com::sun::star::uno;
Sequence<OUString>seqStrlistItems(2);
seqStrlistItems[0]=OUString::createFromAscii("Item1");
seqStrlistItems[1]=OUString::createFromAscii("Item2");

// retrieve them and prints out
for (int i=0;i<seqStrlistItems.getLength();i++){
OString toPrintOut = OUStringToOString(seqStrlistItems[i],RTL_TEXTENCODING_ASCII_US);
printf("-- %s\n",toPrintOut.pData->buffer);
}
</source>
This code prints out in the shell console :
<pre>
-- Item1
-- Item2
[smoutou@p3 Lifetime]$
</pre>

It is easy to understand and therefore I have nothing more to say about it.

===Exercise on Sequence of Strings===
Write and test the following "convert2SeqOUStrInDEBUGMODE" function with a sequence of "sal_Int8" as parameter and which returns a sequence of Strings in a format like the dump method of the old "debug" of DOS. This format [[UNO_registery_and_Bootstrapping#C.2B.2B_Code_to_recover_Information_in_a_Binary_Sequence|will be used here]], but without this function.

'''Solution''' : here is the corresponng function code
<source lang="cpp">
Sequence< OUString > convert2SeqOUStrInDEBUGMODE(Sequence < sal_Int8 > seqBytes){
sal_Int8 Hexa[16]={'0','1','2','3','4','5','6','7','8','9','A','B','C','D','E','F'};
sal_Int32 lin,col;
sal_Char line[80];
sal_Int32 len,sequenceSize,index;
len=seqBytes.getLength();
sequenceSize=(len>>4)+2;
if ((len&0XFFF0)==len) sequenceSize--; //if len%16==0
Sequence< OUString > SeqOUStr(sequenceSize);
// First line with length
SeqOUStr[0] = OUString::createFromAscii("Length:")+
OUString::valueOf((sal_Int32) seqBytes.getLength());
len = len&0XFFF0; // remove the modulo 16
for(lin=0;lin<len;lin=lin+16){
for(col=0;col<16;col++){
line[3*col]=Hexa[((unsigned char)seqBytes[lin+col])>>4];
line[3*col+1]=Hexa[seqBytes[lin+col]&0x0F];
line[3*col+2]=' ';
if ((seqBytes[lin+col]<128)&&(seqBytes[lin+col]>20)) line[50+col]=seqBytes[lin+col];
else line[50+col]='.';
} /* end of for */
line[66]=0; /* end of cstring...*/
line[48]=' ';line[49]=' ';
// ready to add the OUString in Sequence
if ((lin%16)==0) index = lin/16+1; else index=lin/16+2;
SeqOUStr[index]=OUString::createFromAscii(line);
} /* end of for */
// the last line is more complicated because not complete
// we only keep modulo
len=seqBytes.getLength()&0x000F;
if (len>0) { // only a line here if non-empty
for (lin=0;lin<len;lin++){
col=lin;
line[3*col]=Hexa[((unsigned char)seqBytes[lin])>>4];
line[3*col+1]=Hexa[seqBytes[lin]&0x0F];
line[3*col+2]=' ';
if ((seqBytes[lin]<128)&&(seqBytes[lin]>20)) line[50+col]=seqBytes[lin];
else line[50+col]='.';
}
// we complete the line
for (++col;col<16;col++){
line[3*col]=' ';line[3*col+1]=' ';line[3*col+2]=' ';line[50+col]=' ';
}
line[66]=0; /* end of string...*/
line[48]=' ';line[49]=' ';
// ready to add the OUString in Sequence
SeqOUStr[lin/16+2]=OUString::createFromAscii(line);
} //end if
return SeqOUStr;
}
</source>
and now how this function can be used :
<source lang="cpp">
sal_Int8 sourceArray[32]={1,22,23,24,55,56,57,8,9,10,11,12,13,14,15,16,17,18,19,61,62,-32,-33,-34,-35,26,127,-31,29,56,23,67};
Sequence < sal_Int8 > seqBytes(sourceArray,32);
Sequence < OUString > seqOUStr=convert2SeqOUStrInDEBUGMODE(seqBytes);
printf("%s\n",OUStringToOString( seqOUStr[0], RTL_TEXTENCODING_ASCII_US ).pData->buffer);
printf("%s\n",OUStringToOString( seqOUStr[1], RTL_TEXTENCODING_ASCII_US ).pData->buffer);
printf("%s\n",OUStringToOString( seqOUStr[2], RTL_TEXTENCODING_ASCII_US ).pData->buffer);
</source>
In our [[Constructing_Helpers#Reflection_Helper|introspection tool]] we need also this format but in one string. It's easy to write the corresponding code :
<source lang="cpp">
OUString convert2OUStrInDEBUGMODE(Sequence < sal_Int8 > seqBytes){
Sequence <OUString> SeqOUStr = convert2SeqOUStrInDEBUGMODE(seqBytes);
OUString OUStr;
for(sal_Int32 i=0;i<SeqOUStr.getLength();i++)
OUStr = OUStr+SeqOUStr[i]+OUString::createFromAscii("\n");
return OUStr;
}
</source>
which can be used with :
<source lang="cpp">
sal_Int8 sourceArray[32]={1,22,23,24,55,56,57,8,9,10,11,12,13,14,15,16,17,18,19,61,62,-32,-33,-34,-35,26,127,-31,29,56,23,67};
Sequence < sal_Int8 > seqBytes(sourceArray,32);

OUString OUStr=convert2OUStrInDEBUGMODE(seqBytes);
printf("%s\n",OUStringToOString( OUStr, RTL_TEXTENCODING_ASCII_US ).pData->buffer);
</source>

== [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno#Any|Any]] ==
We can find also good materials in Developer's guide on [[Documentation/DevGuide/FirstSteps/Any|Any type]]. [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno#Any|Any]] is easy to use only with <<= and >>= operators and we then often use intermediate variables. We can use also the build-in “makeAny” function :
<source lang="cpp">
// Listing 16 makeAny Example
// C++
Any any = makeAny((long) 1000);
</source>

We give first an example above :

<source lang="cpp">]
//Listing 17 Any Example
// C++
#include <stdio.h>
#include <cppuhelper/bootstrap.hxx>
#include <com/sun/star/uno/Any.hxx>
#include <com/sun/star/uno/Sequence.hxx>
using rtl::OUString;
using rtl::OString;
using com::sun::star::uno::Any;
using namespace com::sun::star::uno;
using namespace rtl;

main( ) {
Any any,any2;
sal_Int32 n=5,n2=18;
any <<= n;
// Gets the type name of the set value
OUString OUStr = any.getValueTypeName();
OString OStr = OUStringToOString( OUStr, RTL_TEXTENCODING_ASCII_US );
printf( "Any type : %s\n", OStr.pData->buffer );// prints out Any type : long
// Tests if any contains a value
if (any.hasValue()) printf("Any has a value\n");// prints out Any has a value
// Clears this any. If the any already contains a value, that value will be destructed and
// its memory freed. After this has been called, the any does not contain a value.
any.clear();
if (any.hasValue()) printf("Any has a value\n");// prints out nothing
any <<= n2;
any2 <<= OUStr;
// Unequality operator: compares two anys. The values need not be of equal type,
// e.g. a short integer is compared to a long integer
if (any != any2) printf("Two different any\n");

Sequence< Any> aValues(2);
aValues[0] <<= (float) 1.1; aValues[1] <<= OUString::createFromAscii("Text");
aValues[1] >>= OUStr;
OStr = OUStringToOString( OUStr, RTL_TEXTENCODING_ASCII_US );
float real;
aValues[0] >>= real;
printf("Seq - length : %d val : %f val %s\n",aValues.getLength(),real,OStr.pData->buffer);
return 0;
}
</source>

This program prints out :
<pre>
Any type : long
Any has a value
Two different any
Seq - length : 2 val : 1.100000 val Text
</pre>
Another important problem is a sequence of sequence of Any : we give now a piece of code without explanation :

<source lang="cpp">
// Listing 18 Sequence of Sequence of Any
// C++
Sequence< Sequence< Any > > aValues(2);
Sequence< Any > aValues2(2);
aValues2[0] <<= (double) 1.1; aValues2[1] <<= OUString::createFromAscii("Hello");
aValues[0] = aValues2;
aValues2[0] <<= (double)2.2; aValues2[1] <<= OUString::createFromAscii("Hi");
aValues[1] = aValues2;
</source>
This code uses two sequences. I have not found an other simpler way to do that. If anybody has a more straightforward solution, I would be happy learn about it.
If it is possible to access directely a value in a 2D array but I found only one means using an intermediate sequence (avalues2) in the case of sequence of sequence.

== Files ==

{{Documentation/Linux|

We want now create a text file named "demo.txt". Here is the code to do this :

<source lang="cpp">
// Listing 19 A little Example manipulating Files
// C++
#include <stdio.h>
#include <cppuhelper/bootstrap.hxx>
#include <osl/file.hxx>

using rtl::OUString;
using rtl::OString;
using namespace osl;

main( ) {
OUString FileName;
sal_Int8 tab[25]="Hi every body\n";
sal_uInt64 nb;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/demo.txt"),FileName);
File myfile(FileName);
myfile.open(OpenFlag_Write);
myfile.write(tab,(sal_uInt64)16,nb);
printf("%d bytes are written\n",nb);
myfile.close();
return 0;
}
</source>
}}
{{Documentation/Note|The method open is not described in C++ documentation !!! I have found it while reading the “file.hxx” header file.}}

The flag you can pass to the "open" method are : OpenFlag_Write, OpenFlag_Read, OpenFlag_Create. The " using namespace osl;" is obligatory even if the compiler doesn't complain without.
When a file is open, you can use the methods above :
<source lang="cpp">
// C++
// Write a number of bytes to a file
write( const void * pBuffer, sal_uInt64 uBytesToWrite, sal_uInt64 & rBytesWritten );

// Read a number of bytes from a file
read( void * pBuffer, sal_uInt64 uBytesRequested, sal_uInt64 & rBytesRead );

// Read a line from a file
ReadLine( ::rtl::ByteSequence & aSeq );

// Test if the end of a file is reached
isEndOfFile( sal_Bool * pIsEOF );

// Retrieve the current position of the internal pointer of an open file
getPos( sal_uInt64 & uPos );

// Set the internal position pointer of an open file.
setPos( sal_uInt32 uHow, sal_Int64 uPos );
</source>
There are other possibilities : move, remove, copy... See the documentation or read the file.hxx file.

See [http://udk.openoffice.org/common/man/concept/streams.html « Streaming interfaces »]
for an other way to use files.

== Threads ==

It would be great to use the Thread Class but it's so badly documented that we begin with process instead thread.
Starting from an example posted in the forum Working with a Spreadsheet Document in C++ (by lirincy). This example gives a working code to start OOo if not started when launching a binary executable. We remove what was not usefull for us and give two examples.
{{Documentation/Linux|
<source lang="cpp">
// Listing 20 A Process Example
// C++
#include <stdio.h>
#include <cppuhelper/bootstrap.hxx>
#include <osl/process.h>
#include <osl/file.hxx>

using rtl::OUString;
using rtl::OString;

main( ) {
// Don't forget to add #include <osl/process.h>
oslProcess hProcess = NULL;
// Don't forget to add #include <osl/file.hxx>
OUString FileURL;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/demo"),
FileURL
);
oslProcessError osl_error = osl_executeProcess(
FileURL.pData,
NULL,
0,
osl_Process_DETACHED,
0, /* osl_getCurrentSecurity() */
NULL,
NULL,
0,
&hProcess );
osl_error = osl_joinProcess(hProcess);
return 0;
}
</source>
}}
{{Documentation/Note|Note that the demo file is an existing binary in /home/smoutou.}}
If you want to pass something to the launched program see AppArgs variable in the second example :
{{Documentation/Linux|
<source lang="cpp">
// Listing 21 A second Process Example
// C++
#include <stdio.h>
#include <cppuhelper/bootstrap.hxx>
#include <osl/process.h>
#include <osl/file.hxx>

using rtl::OUString;
using rtl::OString;

main( ) {
// Don't forget to add #include <osl/process.h>
oslProcess hProcess = NULL;
// Don't forget to add #include <osl/file.hxx>
OUString FileURL;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/demo"),
FileURL
);
OUString AppArgs = OUString::createFromAscii("Arg1");
oslProcessError osl_error = osl_executeProcess(
FileURL.pData,
&AppArgs.pData,
1,
osl_Process_DETACHED,
0, /* osl_getCurrentSecurity() */
NULL,
NULL,
0,
&hProcess );
osl_error = osl_joinProcess(hProcess);

return 0;
}
</source>
}}
I have tried working with thread but only with C style at the moment (not with using the thread class). Here is my first example code :
{{Documentation/Linux|
<source lang="cpp">
// Listing 22 A working Thread Example
// C++
#include <stdio.h>
#include <cppuhelper/bootstrap.hxx>
#include <osl/thread.h>
#include <unistd.h> // LINUX

using rtl::OUString;
using rtl::OString;

/** wait _nSec seconds.
*/
void thread_sleep( sal_Int32 _nSec )
{
/// print statement in thread process must use fflush() to force display.
printf("# wait %d seconds. ", _nSec );
fflush( stdout );
sleep( _nSec );
printf("# done\n" );
}

void SAL_CALL thread1(void *) {
while(1)
printf("\n thread running");

}

void SAL_CALL thread2(int *nb){
while(1)
printf("\n thread nb=%d running",*nb);
}

main( ) {
// Don't forget to add #include <osl/thread.h>
oslThread hThread = NULL;
//oslWorkerFunction type : void (SAL_CALL *oslWorkerFunction)(void*); in osl/thread.h
oslWorkerFunction pFunction = (void (SAL_CALL *)(void*)) thread2;
int pthreaddata=2;
// create and start the thread2 with 2 as a parameter value
oslThread hThread2 = osl_createThread(pFunction,(void *) &pthreaddata);
// create and start the thread1
hThread = osl_createThread(thread1,NULL);

thread_sleep(2);
osl_suspendThread(hThread);
osl_suspendThread(hThread2);

return 0;
}
</source>
}}
What is printed out is depending on how screen is managed by your OS. Under Linux I obtained something like :
<pre>
...
thread running
thread running
thread running
thread running# done

thread nb=2 running
thread nb=2 running
thread nb=2 running
thread nb=2 running
....
</pre>
Here you can see the second thread launched writes at first and only when the main sleeping is terminated thread two is writing out. The other thread primitives can be found in osl/thread.h :
<pre>
/** Create the thread, using the function-ptr pWorker as
its main (worker) function. This functions receives in
its void* parameter the value supplied by pThreadData.
Once the OS-structures are initialized,the thread starts
running.
@return 0 if creation failed, otherwise a handle to the thread
*/
oslThread SAL_CALL osl_createThread(oslWorkerFunction pWorker, void* pThreadData);

/** Create the thread, using the function-ptr pWorker as
its main (worker) function. This functions receives in
its void* parameter the value supplied by pThreadData.
The thread will be created, but it won't start running.
To wake-up the thread, use resume().
@return 0 if creation failed, otherwise a handle to the thread
*/
oslThread SAL_CALL osl_createSuspendedThread(oslWorkerFunction pWorker, void* pThreadData);

/** Release the thread handle.
If Thread is NULL, the function won't do anything.
Note that we do not interfere with the actual running of
the thread, we just free up the memory needed by the handle.
*/
void SAL_CALL osl_destroyThread(oslThread Thread);

/** Wake-up a thread that was suspended with suspend() or
createSuspended(). The oslThread must be valid!
*/
void SAL_CALL osl_resumeThread(oslThread Thread);

/** Suspend the execution of the thread. If you want the thread
to continue, call resume(). The oslThread must be valid!
*/
void SAL_CALL osl_suspendThread(oslThread Thread);
/** Returns True if the thread was created and has not terminated yet.
Note that according to this definition a "running" thread might be
suspended! Also returns False is Thread is NULL.
*/
sal_Bool SAL_CALL osl_isThreadRunning(const oslThread Thread);

/** Blocks the calling thread until Thread has terminated.
Returns immediately if Thread is NULL.
*/
void SAL_CALL osl_joinWithThread(oslThread Thread);

/** Blocks the calling thread at least for the given number
of time.
*/
void SAL_CALL osl_waitThread(const TimeValue* pDelay);
</pre>

For more information you can read [[Uno/Article/Multi-Thread_Programming|Multi-Thread Programming]].

== To go further : the Enumeration Type Problem ==
Sometimes we will encounter enumeration values. We have to learn how to resolve the problem. An example will be discussed later but we give it without its context here. The Cell content in OOoCalc is described by an enumeration. How can I know that, is not easy with the previous material, but I want to tackle the problem even if too soon to understand for a first reading.

All types used in programming are described in IDL files. Sometimes these IDL files are used to create hpp/hxx files.

This example is around CellContentType.idl file. Here is the summary of this file where we remove comments :

<source lang="idl">
// Listing 23 CellContentType Enumeration type (IDL File)
// IDL
namespace com{
namespace sun{
namespace star{
namespace table{
enum CellContentType
{
CellContentType_EMPTY = 0,
CellContentType_VALUE = 1,
CellContentType_TEXT = 2,
CellContentType_FORMULA = 3,
CellContentType_MAKE_FIXED_SIZE = SAL_MAX_ENUM
};
} // table
} // star
} // sun
} // com
</source>
Three tips can be used when using this kind of enumeration :
* In C++ a corresponding using namespace is necessary
using namespace com::sun::star::table
This line can be drawn from the IDL file.
* In C++ an include directive is necessary
<source lang="cpp">
#include <com/sun/star/table/CellContentType.hpp>
</source>
The name of the file to include and the path is easy to draw from IDL file.
* We have to construct the previous hpp file. This is done with adding the red line above in the makefile :
<pre>
TYPES := \
com.sun.star.uno.XNamingService \
com.sun.star.uno.XComponentContext \
com.sun.star.uno.XWeak \
com.sun.star.uno.XAggregation \
com.sun.star.lang.XMain \
com.sun.star.lang.XMultiServiceFactory \
com.sun.star.lang.XSingleComponentFactory \
com.sun.star.lang.XTypeProvider \
com.sun.star.lang.XComponent \
com.sun.star.registry.XSimpleRegistry \
com.sun.star.registry.XImplementationRegistration \
com.sun.star.bridge.XBridgeFactory \
com.sun.star.bridge.XUnoUrlResolver \
com.sun.star.table.CellContentType \
com.sun.star.container.XHierarchicalNameAccess
</pre>
After you can use this enumeration without problem like this :
<source lang="cpp">
// Listing 24 Enumeration type : an Example
//C++
// To check
// Don't forget to add #include <com/sun/star/table/CellContentType.hpp>
// Don't forget to add "com.sun.star.table.CellContentType \" in the makefile

using namespace com::sun::star::table
short enumval;
enumval = CellContentType_EMPTY;
switch (enumval){
case CellContentType_EMPTY : printf("Empty\n");break;
case CellContentType_VALUE : printf("Numerical Value\n");break;
case CellContentType_TEXT : printf("Text\n");break;
case CellContentType_FORMULA : printf("Formula\n");break;
}
</source>
What is shown here is a general SDK's feature : we construct a hpp file starting from an IDL file. This is so important and unexpected for beginners that I will repeat many times these explanations [[UNO_automation_with_a_binary_%28executable%29#Introduction_to_Bootstrapping|later]] and more deeply [[IDL_Files_and_Cpp#Getting_an_interface_in_C.2B.2B|here]].

== To go further : the Constant Type Problem ==
Values are not always defined with enumeration types as shown in previous section. Sometimes constants are used when programming with UNO. One example is again tackled [[OpenOffice_Calc#The_Compute_Function__Example|later]] but we want again writes on it now. We first present the corresponding IDL file (as an example)

<source lang="idl">
// Listing 25 CellFlags Constants type : IDL File
//IDL
module com { module sun { module star { module sheet {
constants CellFlags
{
const long VALUE = 1;
const long DATETIME = 2;
const long STRING = 4;
const long ANNOTATION = 8;
const long FORMULA = 16;
const long HARDATTR = 32;
const long STYLES = 64;
const long OBJECTS = 128;
const long EDITATTR = 256;
};
}; }; }; };
</source>
Compare this listing with Listing 23 to see the differences.
If you want to use the constants above you first generate the corresponding hpp file with modifying the makefile as in previous section, and then add the corresponding include directive :
<source lang="cpp">
// C++
#include <com/sun/star/sheet/CellFlags.hpp>
</source>
in your C++ code. Note that with this include directive you can directly write something like
<source lang="cpp">
// C++
VALUE | DATETIME
</source>
instead of
<source lang="cpp">
// C++
CellFlags_VALUE | CellFlags_DATETIME
</source>
as seen previously.

==Going further with Sequences==
We want to give any utilities used later in this document.
===Converting Sequences into Array===
Because it exists a correponding member function this conversion is very easy :
<source lang="cpp">
//Listing 27 Conversion Example
// C++
Sequence < sal_Int32 > SetOfInt(5);
sal_Int32 *table;
table = SetOfInt.getArray();
</source>
If you read carefully to this point, this code is familiar for you : it's drawn from Listing 4 and then already explained.
===Converting Sequence of Sequence into Array===
This problem has to be solved. We will use this kind of conversion later (see chapter 14). We first give two subprograms, to print out and to convert :
<source lang="cpp">
//Listing 28 Sequence of Sequence into 1D array
//C+
// Sequence of Sequence is printed out like that :
// toPrint[0][0] toPrint[0][1] toPrint[0][2]...
// toPrint[1][0] toPrint[1][1] toPrint[1][2]...
// ...
// Note that i denotes the first index
void printOutSeqSeq(const Sequence < Sequence < double > > &toPrint){
cout << "Prints out SeqSeq" << endl;
for(int i=0;i<toPrint.getLength();i++){
Sequence < double > rLine = toPrint[i];
double *line= rLine.getArray();
for(int j=0;j<rLine.getLength();j++)
cout << " " << line[j] << " ";
cout << endl;
}
}

double *SeqSeqToArray1D(const Sequence < Sequence < double> > &seqseq){
sal_Int32 iMax=seqseq.getLength(),jMax;
Sequence < double > rLine = seqseq[0];
jMax=rLine.getLength();
double *table1D = new double[iMax*jMax];
for (sal_Int32 i = 0 ; i < iMax; i++ )
for(sal_Int32 j = 0 ; j < jMax; j++ )
table1D[i*jMax+j]= seqseq[i][j];
return table1D;
}
</source>
Using these sub is easy : it can be done like that :
<source lang="cpp">
//Listing 29 Using the conversion
//C+
// We first construct a sequence
Sequence < double > demo(5);
demo[0]=1.1;
demo[1]=2.1;
demo[2]=3.1;
demo[3]=4.1;
demo[4]=5.1;
// We then construct the sequence of sequence
Sequence < Sequence < double > > seqseq(3);
for (int i=0; i<seqseq.getLength();i++)
seqseq[i]=demo;
// We print out the result of the construction
printOutSeqSeq(seqseq);
// Here is the conversion
double *table = SeqSeqToArray1D(seqseq);
// We finish wit printing out the result
cout << "Array1D -> 2D : "<< endl;
for (int i=0; i< 3; i++){
for (int j=0;j<5;j++)
cout<<" "<<table[i*5+j]<<" ";
cout<<endl;
}
....
delete table;
</source>
which gives us :
<pre>
Prints out SeqSeq
1.1 2.1 3.1 4.1 5.1
1.1 2.1 3.1 4.1 5.1
1.1 2.1 3.1 4.1 5.1
Array1D -> 2D :
1.1 2.1 3.1 4.1 5.1
1.1 2.1 3.1 4.1 5.1
1.1 2.1 3.1 4.1 5.1
[smoutou@p3 Lifetime]$
</pre>
Converting a sequence of sequence directly in an 2D array is not an easy task because the compiler has to know the size of the second index before compiling. At first something like
<source lang="cpp">
//Listing 30 Array2D conversion
// C++
double **SeqSeqToArray2D(const Sequence < Sequence < double> > &seqseq){
double **table2D;
double *table1D;
table1D = SeqSeqToArray1D(seqseq);
table2D = &table1D;
return table2D;
}
</source>
seems interesting but let's see if that works out. A first idea is to write something like :
<source lang="cpp">
//Listing 31 Wrong code for conversion
// C++
double **table2= SeqSeqToArray2D(seqseq);
for (int i=0; i< 3; i++){
for (int j=0;j<5;j++)
cout<<" "<< table2[i][j]<<" ";
cout<<endl;
}
delete table2;
</source>
but the compiler is unable to calculate table2[i][j] here. For that it has to evaluate the expression i*jMax+j but has no knowledge on jMax !!

===More Abstractions with STL===
If you plan to use C++ you will certainly use the STL extensively. We begin first by conversions. Here is the easier one :
<source lang="cpp">
//Listing 32 Converting a Sequence of Sequence into a vector
// C++
// Inspired by Eric Ehlers's code but using template
// See chapter 14
template< typename T>
vector < T >SeqSeqToVectorTemplate(const Sequence< Sequence < T > >& ss) {
vector < T >v;
for (int i=0; i<ss.getLength(); i++)
for (int j=0; j<ss[i].getLength(); j++)
v.push_back(ss[i][j]);
return v;
}
</source>
My start point for achieving this code was Eric Ethler's code presented [[CompleteAddIn#Transforming_an_Array_into_Sequence_of_Sequence|here]]. This code is again easy to use :
<source lang="cpp">
//Listing 33 Using the previous Convertion
// C++
#include <iostream>
#include<vector>
#include <cppuhelper/bootstrap.hxx>
#include <com/sun/star/uno/Sequence.hxx>
using namespace com::sun::star::uno;
using namespace std;

template< typename T>
vector < T >SeqSeqToVectorTemplate(const Sequence< Sequence < T > >& ss);
main( ) {
Sequence < double > demo(5);
demo[0]=1.1;
demo[1]=2.1;
demo[2]=3.1;
demo[3]=4.1;
demo[4]=5.1;
Sequence < Sequence < double > > seqseq(3);
// simply use the same sequence
for (int i=0; i<seqseq.getLength();i++)
seqseq[i]=demo;
// template
vector <double> v=SeqSeqToVectorTemplate(seqseq);
cout << "vector1D -> 2D : "<< endl;
for (int i=0; i< 3; i++){
for (int j=0;j<5;j++)
cout<<" "<<v[i*5+j]<<" ";
cout<<endl;
}
return 0;
}
</source>
We give now three other conversions (see also [[CompleteAddIn#Transforming_an_Array_into_Sequence_of_Sequence|here]])
<source lang="cpp">
//Listing 34 Converting Utilities with Template
// C++
// Inspired by Eric Ethler's code but using template
// See chapter 14
template< typename T>
Sequence< Sequence< T > > VectorTemplateToSeqSeq(const vector < T > &v) {
Sequence< Sequence< double > > ss(v.size());
for (unsigned int i=0; i<v.size(); i++) {
Sequence< T > s(1);
s[0] = v[i];
ss[i] = s;
}
return ss;
}
template< typename T>
vector < vector < T > >SeqSeqToMatrixTemplate(const Sequence< Sequence < T > >& ss) {
vector < vector < T > >vv;
for (int i=0; i<ss.getLength(); i++) {
vector < T >v;
for (int j=0; j<ss[i].getLength(); j++)
v.push_back(ss[i][j]);
vv.push_back(v);
}
return vv;
}
template< typename T>
Sequence< Sequence< T > > MatrixTemplateToSeqSeq(
const std::vector < std::vector < T > >&vv) {
Sequence< Sequence< T > > ss(vv.size());
for (unsigned int i=0; i<vv.size(); i++) {
std::vector < T > v = vv[i];
Sequence< T > s(v.size());
for (unsigned int j=0; j<v.size(); j++)
s[j] = v[j];
ss[i] = s;
}
return ss;
}
</source>
One way to use it is for instance :
<source lang="cpp">
//Listing 35 Converting Utilities with Template
//C++
...
// seqseq must be initialized
vector <vector <double> > v2=SeqSeqToMatrixTemplate(seqseq);
cout << "vector2D : "<< endl;
for (int i=0; i< 3; i++){
for (int j=0;j<5;j++)
cout<<" "<<v2[i][j]<<" ";
cout<<endl;
}
</source>
Because there is a lot of algorithms based on STL I think these utilities will be very helpfull.

{{Template:Home_Page}}

= See also =
* [[FR/Documentation/Cpp_Guide|French version of this chapter]].
* [[Uno/Article/Understanding_Uno|Understanding Uno]]
* [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno|C++ and UNO tutorial]]
* [[Uno/Article/Multi-Thread Programming | Multi-Thread Programming]]
* To learn C++ : [http://www.smart2help.com/e-books/ C++ e-books]
* [http://en.wikibooks.org/wiki/Programming:Data_Structures Wiki on C++ Data Structures]
* [[Uno/Binary/Analysis/String_Performance|String Performance]]
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal

[[Category:Tutorial]]
[[Category:Cpp]]
[[Category:Uno]]

Using Cpp with the OOo SDK

2014-07-11T00:33:58Z

Global667: Delete off topic link

{{Documentation/Banner}}
[[Image:HomePageCpp.png]]

This site is about using C++ as a language to program OpenOffice extensions.
* [[CppSDKAuthors|About the Author and Contributors]]
* [[SDKInstallation|How to install the SDK and compile the C++ examples]]
* [[SDKCppLanguage|The UNO C++ Language]]
* [[UNO_automation_with_a_binary_(executable)|OpenOffice.org's UNO automation with a binary (executable)]]
* [[Calc/API/Programming|OpenOffice Calc]]
* [[Programming_OOoDraw_and_OOoImpress|C++ automation of OOoDraw and OOoImpress]]
* [[Working_with_Shapes |Working with Shapes in C++]]
* [[Programming OooWriter |Programming OooWriter with C++]]
* General Utilities
**[[Playing_with_Window_Toolkit_AWT|Playing with Window Toolkit AWT]]
**[[Executing_an_OOoBasic_macro_with_Cpp|Executing an OOoBasic macro with C++]]
* [[IDL_Files_and_Cpp|IDL Files and C++]]
* [[UNO_registery_and_Bootstrapping|UNO registery and Bootstrapping]]
* [[Constructing_Helpers|Constructing Helpers]]
* [[Constructing_Components|Constructing Components in C++]]
* [[Component_and_Dialog|Managing a Dialog in a Component]]
* [[Going_further_with_Dialog_and_Component|Going further with Dialog and Components]]
* [[Add-on|Constructing an Addon]]
* [[CompleteAddIn | OOoCalc addin in C++]]
* [[Writing_Professional_Components|Writing professional Components]]
* [[XML_and_Filter |XML, Filters and Files]]
* [[MakeFile|Appendix : Using make utility]] with SDK
* [[GNU_Lesser_General_Public_License|GNU Lesser General Public License]]

{{Documentation/Caution|I have decided to give up with this C++ documentation. My last work was to add two chapters in summer 2009. I have done nothing more during last year. I only want to say this document is completely free, unfortunatly is not finished (particularly with addon and dialog). Please let this caution banner for a year and remove it after because tradition in OpenOffice documentation is to remove author's names. After a year, it would be also great to remove my name everywhere it appears in other chapters. Thank you in Advance. [[User:SergeMoutou|SergeMoutou]] 08:52, 26 August 2010 (UTC)}}
= See also=
== General ==
* [[FR/Documentation/Cpp_Guide|French version of this document]].
* [[Documentation/DevGuide/OpenOffice.org_Developers_Guide | Developer's Guide]]
* [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno|C++ and UNO tutorial]]
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal
* [[Tutorial_UNO_Library|UNO tutorial]]
* [[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [http://udk.openoffice.org/common/man/concept/unointro.html UNO Introduction]
* [http://www.oooforum.org/forum/viewtopic.phtml?t=8702 Working with a database in C++] (not tackled in this document at the moment).
* [[Compiler_versions_used_by_port_maintainers_and_release_engineers|Compiler versions used by port maintainers and release engineers]]

== Coding ==
* [[Writing_correct_Cplusplus|Writing correct C++]]
* [[Writing_warning-free_code|Writing warning-free code]]
* [[Debugging |Debugging]]

[[Category:Tutorial]]
[[Category:Cpp]]
[[Category:Documentation/Developer's Guide]]
[[Category:Uno]]
[[Category:Article]]

SDKInstallation

2014-07-10T21:46:36Z

Global667: /* How to install the SDK and compile the C++ examples */ Add help suggestions

{{Documentation/Banner}}
= How to install the SDK and compile the C++ examples =

The following points are important, if you want to succeed in building C++ components and snippets:
* You need to have OpenOffice.org and OpenOffice SDK in the identical version
* You need to install the SDK into a directory other than the one of the AOO application
* It is strongly recommended to install the newest Java JDK on your system
* Make your operating system up to date
* If you have questions, use your preferred search engine first. If this not works visit: https://forum.openoffice.org to get help.

== Installation under Mac OS X ==
{{Documentation/OSX|
The text below describes the installation of the SDK 4.1.0 and OpenOffice 4.1.0 on Mac OS X 10.9.4 with Xcode 4.1.1. It would works for other Intel Mac configurations too.
* Install Xcode. You can get it from the Apple App Store. Perhaps you must be registered as Mac developer under https://developer.apple.com
* Install newest OpenOffice and the corresponding SDK from http://openoffice.apache.org/downloads.html (Choose MacOS_x86-64)
* (Optional) Install MacPorts from http://www.macports.org. You need MacPorts to install optional Unix-like software needed by the SDK.
* Test the SDK. Open a terminal and look for the SDK folder. Now type and run:
<pre>
cd <SDK_Folder>
./setsdkenv_unix # Need to run every time before you use the SDK
cd examples/cpp/DocumentLoader
make
soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager" &
make DocumentLoader.run
</pre>
If everything went fine, you should see a new document, with the content of <SDK_Folder>/examples/cpp/DocumentLoader/test.odt.

Further informations see: http://www.openoffice.org/api/SDK/ and [[Documentation/DevGuide]]

Its recommended to use Eclipse or Netbeans to develop with OpenOffice SDK. There are plugins for booth, but they don't support C++ programming. Feel free to help adding this feature: For Eclipse visit [[OpenOffice_Eclipse_Integration]]. For Netbeans visit [[OpenOffice_NetBeans_Integration]].

To work with the SDK and C++ use an editor of your choice.
}}

== Installation under LINUX ==
{{Documentation/Linux|
The text below describe the installation of the SDK 4.1.0 for OpenOffice.org 4.1.0 under Ubuntu.
* Make sure you have development tools installed:
<pre>
sudo aptitude install gcc make build-essential
</pre>
* Install newest OpenOffice and the corresponding SDK from http://openoffice.apache.org/downloads.html or type and run
<pre>
sudo aptitude install openoffice.org openoffice.org-dev openoffice.org-dev-doc
</pre>
* Test the SDK. Open a terminal and look for the SDK folder. Now type and run:
<pre>
cd <SDK_Folder>
./setsdkenv_unix # Need to run every time before you use the SDK
cd examples/cpp/DocumentLoader
make
soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager" &
make DocumentLoader.run
</pre>
If everything went fine, you should see a new document, with the content of <SDK_Folder>/examples/cpp/DocumentLoader/test.odt.

Further informations see: http://www.openoffice.org/api/SDK/ and [[Documentation/DevGuide]]

Its recommended to use Eclipse or Netbeans to develop with OpenOffice SDK. There are plugins for booth, but they don't support C++ programming. Feel free to help adding this feature: For Eclipse visit [[OpenOffice_Eclipse_Integration]]. For Netbeans visit [[OpenOffice_NetBeans_Integration]].

Bear in mind the easier way to construct the examples of the SDK is to use the makefiles provided. If you want to start a project, begin with modifying an example of the SDK.
}}

{{Documentation/NeedsRework}}
== Installation under Windows ==
{{Documentation/Windows|

You need a compiler out of the Microsoft Visual Studio family (other compilers like MinGW have turned out to be hard to configure for OOo on Windows).
The first thing after having installed the SDK is to launch the configureWindowsNT.bat and set all the necessary directories for proper use of the SDK.
If that has been done you have already installed everything, but *wait* one very important thing you should still know of:
Every time you want to run your own code or one of the SDK examples you need to launch the setsdkenv_Windows batch file from your command shell. The title of it should now be "Shell prepared for SDK". Happy coding, compiling and building now (I tell you it's easy from now on!).
GanescuCarmen describes some problems he encounter when trying SDK examples under Windows :
“I also use the 1.1 OO version.

I had a lots of problems.
Finally I succeeded to obtain the the header files, and in VC I needed some library to be included into project and some files(uno.idl) to be added to rdb files.
It was very hard to understand what it means registry(the rdb file not the Registry itself).

I was expecting to register something in Registry but it wasn't like this.
And with the service manager I had some problems, with the port, because the connection with 8100 port was not done.
I had to modify a file and to add some code for 8100 port.

But I did it and it works now.”
}}

=== Installing with the free MS Visual C++ Toolkit 2003 ===
{{Documentation/HelpNeeded|This section needs help for update because '''MS Visual C++ Toolkit 2003''' seems no more available. Please have a look at Microsoft for the free Visual C++ tools at the moment.}}
I have installed DevCpp to have a make executable file.
I have downloaded the free Visual C++ Toolkit 2003 here :
http://www.microsoft.com/downloads/details.aspx?FamilyID=272be09d-40bb-49fd-9cb0-4bfa122fa91b&displaylang=en

and then I have installed it. '''(This link is broken.)'''

I launch first C:\openoffice\OpenOffice.org2.0_SDK\configureWindowsNT.bat
which asks any questions :
<pre>
set OO_SDK_HOME=C:\openoffice\OpenOffice.org2.0_SDK
set OFFICE_HOME=C:\Program Files\OpenOffice.org 2.0
set OO_SDK_MAKE_HOME=C:\Dev-C++\Bin
set OO_SDK_CPP_HOME=C:\Program Files\Microsoft Visual C++ Toolkit 2003\Bin
set OO_SDK_JAVA_HOME=C:\Program Files\Java\jdk1.5.0_03
</pre>

and I am ready to launch setsdkenv_windows.bat

I have modified the following file :
C:\openoffice\OpenOffice.org2.0_SDK\examples\DevelopersGuide\ProfUNO\CppBinding\office_connect.cxx
to change the port accordingly to what OOo is listening.

I have modified the makefile :
added :
<pre>
CC_INCLUDES = -I"C:\Program Files\Microsoft Visual C++ Toolkit 2003\include" \
-I"C:\openoffice\OpenOffice.org2.0_SDK\include"
</pre>

and added libraries too :

<pre>
$(OUT_BIN)/%$(EXE_EXT) : $(SAMPLE_OBJ_OUT)/%.$(OBJ_EXT)
-$(MKDIR) $(subst /,$(PS),$(@D))
-$(MKDIR) $(subst /,$(PS),$(SAMPLE_GEN_OUT))
ifeq "$(OS)" "WIN"
$(LINK) $(EXE_LINK_FLAGS) /OUT:$@ /MAP:$(SAMPLE_GEN_OUT)/$(subst $(EXE_EXT),.map,$(@F)) \
$< $(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB)\
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libcp.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libc.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\oldnames.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\kernel32.lib"
else
$(LINK) $(EXE_LINK_FLAGS) $(LINK_LIBS) -o $@ $< \
$(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB) $(STDC++LIB)
endif
</pre>
I suppose there is a more straightforward way to add these libraries with adding the corresponding include path but I am unable to do that with VC++.

I find a solution of the previous problem three weeks later. My problem comes in fact from a bug in setsdkenv_windows.bat. A little correction in the file setsdkenv_windows.bat makes it possible to avoid the makefile modifications :
Put :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "C:\Program Files\Microsoft Visual C++ Toolkit 2003\VCVARS32.bat"
</pre>

instead of :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "%OO_SDK_CPP_HOME%\VCVARS32.bat"
</pre>
I think
<pre>
%OO_SDK_CPP_HOME%\..\VCVARS32.bat
</pre>
could work too (but not checked). You can also move vcvars32.bat in %OO_SDK_CPP_HOME%
("C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin" for me).

=== Other Windows Installations descriptions ===

You can find in [http://www.oooforum.org/forum/viewtopic.phtml?t=23772 OOoForum] a post entitled Guide for develop OpenOffice apps with VC++ .net (by [[CppSDKAuthors|LarsB]])

1.Download and install OpenOffice.

2.Download and install OpenOffice SDK

3.Create a new folder inludecpp in <oo_sdk_path>

4.Open Dos console change directory to <oo_sdk_path>\windows\bin

4.1 run cppumaker with followig paramerers
<pre>
cppumaker -BUCR -O <oo_sdk_path>\includecpp <office_programm_dir>\types.rdb
</pre>
or better with
<pre>
cppumaker -Gc -BUCR -O<includes_path> <ooffice_path>\URE\misc\types.rdb <ooffice_path>\Basis\program\offapi.rdb
</pre>
in recent versions.

(Attention: If you recieve a init error, copy types.rdb into the <oo_sdk_path>\windows\bin folder!)
After that all hpp and hdl files should be created in <oo_sdk_path>\includecpp

5.Open Visual Studio and create a new Win32 Console Application.
Applay the following changes to your project.

5.1. Tools ->Options->Projects->VC++ Directories -> Include Files
Add \include directory and <oo_sdk_path>\includecpp

5.2. Tools ->Options->Projects->VC++ Directories -> Library files
Add <oo_sdk_path>\windows\lib directory

5.3. Tools ->Options->Projects->VC++ Directories -> Executable files
Add <office_programm_dir>\program directory (location where you installed the version of the OpenOffice)

5.4 Open the Project Settings

5.4.1 Change Configuration to all All Configurations (the combobox in the left corner of the window)

5.4.2 Add the additional libraries

Properties->Linker->ComandLine in the Additional Options tab the library files
isal.lib icppu.lib icppuhelper.lib isal.lib isalhelper.lib ireg.lib irmcxt.lib stlport_vc71.lib

6.(example) Add the DocumentLoader.cxx from the cpp examples of the sdk
and compile. The source should compile without errors.

INFO : If you got the following error have a look at the solution 2 postings above!
Up to now, with the steps above i got the following error, when i run the DocumentLoader example.
The error is thrown, when the prog execution reach the following line:

<pre>

Reference< XSimpleRegistry > xSimpleRegistry( ::cppu::createSimpleRegistry() );
</pre>

with error shown below :

<pre>
Error:
Window title: Microsoft Visual C++ Debug Library
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

If somebody has experience with this kind of error it will be nice if he could
post a solution. So that here is a complete little guide for OpenOffice with VC++ .NET

Regards
[[CppSDKAuthors|Lars]]

[[CppSDKAuthors|François]] has improved the complete procedure with remarks :
Following all the steps I (_francois_) encountered two problems

* first in point 4.4.2

But there I guess it's because the procedure was meant for SDK 2 and I'm using SDK 1.1
The stlport_vc71.lib which you must include is distributed with the SDK 2 in the SDK 1.1 stlport_vc7.lib
you just need to include the stlport_vc7.lib instead of stlport_vc71.lib

* second problem after successfuly compiling the DocumentLoader in Visual Studio I was getting the following error
Error:
<pre>
Window title: Microsoft Visual C++ Debug Libary
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

After going on debug in the visual studio I found the following line was responsible

<pre>
xSimpleRegistry->open( OUString( RTL_CONSTASCII_USTRINGPARAM("DocumentLoader.rdb") ), sal_True, sal_False );
</pre>

The DocumentLoader.rdb was missing ... I noticed that if I compiled the DocumentLoader exemples from command line with the makefile provided with the exemple a DocumentLoader.rdb was generated. I had a look at the Makefile I isolated the lines which seemed to generate the DocumentLoader.rdb into my Debug folder (or wherever your set your DocumentLoader.exe to be put by Visual Studio) in my Visual Studio project...

<pre>
regmerge c:\travail\DocumentLoader\debug\DocumentLoader.rdb / "C:\ooo\office\program\types.rdb"

regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c connector.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c remotebridge.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c bridgefac.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c uuresolver.uno.dll
</pre>

I launched all the above lines in the prompt shell and it worked I had my DocumentLoader.rdb in my Debug folder

I launched my exe file and it worked, great...

Now I guess I still need to figure out which *.uno.dll needs to be included for which functions used in the programm, but still it's a good start.
If anyone has any information about that (It may actualy be documented somewhere) don't hesitate)

== The Development Tools of the SDK ==

There are several development tools provided with the SDK : idlc, cppumaker, javamaker, rdbmaker, pkgchk, regcomp, regmerge, regview, xml2cmp, uno, and autodoc. You can find a short documentation on these tools at <OOo_SDK>/docs/tools.html and also in [[Documentation/DevGuide/WritingUNO/Required_Files|Developer's Guide]].

See also [[Compiler_versions_used_by_port_maintainers_and_release_engineers|Compiler versions used by port maintainers and release engineers]]

{{Template:Home_Page}}

= See also =
* [[FR/Documentation/Installation_du_SDK|French version of this chapter]].
* [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno|C++ and UNO tutorial]]
* [http://www.codeproject.com/KB/wtl/Wtl_OOo.aspx Prepare the OOo SDK]
* [http://www.oooforum.org/forum/viewtopic.phtml?t=79911&highlight= missing files in sdk]
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal

[[Category:Tutorial]]
[[Category:Cpp]]
[[Category:Uno]]

SDKInstallation

2014-07-10T21:39:39Z

Global667: Tagging win section only as NeedsRework

{{Documentation/Banner}}
= How to install the SDK and compile the C++ examples =

The following points are important, if you want to succeed in building C++ components and snippets:
* You need to have OpenOffice.org and OpenOffice SDK in the identical version
* You need to install the SDK into a directory other than the one of the AOO application
* It is strongly recommended to install the newest Java JDK on your system
* Make your operating system up to date

== Installation under Mac OS X ==
{{Documentation/OSX|
The text below describes the installation of the SDK 4.1.0 and OpenOffice 4.1.0 on Mac OS X 10.9.4 with Xcode 4.1.1. It would works for other Intel Mac configurations too.
* Install Xcode. You can get it from the Apple App Store. Perhaps you must be registered as Mac developer under https://developer.apple.com
* Install newest OpenOffice and the corresponding SDK from http://openoffice.apache.org/downloads.html (Choose MacOS_x86-64)
* (Optional) Install MacPorts from http://www.macports.org. You need MacPorts to install optional Unix-like software needed by the SDK.
* Test the SDK. Open a terminal and look for the SDK folder. Now type and run:
<pre>
cd <SDK_Folder>
./setsdkenv_unix # Need to run every time before you use the SDK
cd examples/cpp/DocumentLoader
make
soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager" &
make DocumentLoader.run
</pre>
If everything went fine, you should see a new document, with the content of <SDK_Folder>/examples/cpp/DocumentLoader/test.odt.

Further informations see: http://www.openoffice.org/api/SDK/ and [[Documentation/DevGuide]]

Its recommended to use Eclipse or Netbeans to develop with OpenOffice SDK. There are plugins for booth, but they don't support C++ programming. Feel free to help adding this feature: For Eclipse visit [[OpenOffice_Eclipse_Integration]]. For Netbeans visit [[OpenOffice_NetBeans_Integration]].

To work with the SDK and C++ use an editor of your choice.
}}

== Installation under LINUX ==
{{Documentation/Linux|
The text below describe the installation of the SDK 4.1.0 for OpenOffice.org 4.1.0 under Ubuntu.
* Make sure you have development tools installed:
<pre>
sudo aptitude install gcc make build-essential
</pre>
* Install newest OpenOffice and the corresponding SDK from http://openoffice.apache.org/downloads.html or type and run
<pre>
sudo aptitude install openoffice.org openoffice.org-dev openoffice.org-dev-doc
</pre>
* Test the SDK. Open a terminal and look for the SDK folder. Now type and run:
<pre>
cd <SDK_Folder>
./setsdkenv_unix # Need to run every time before you use the SDK
cd examples/cpp/DocumentLoader
make
soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager" &
make DocumentLoader.run
</pre>
If everything went fine, you should see a new document, with the content of <SDK_Folder>/examples/cpp/DocumentLoader/test.odt.

Further informations see: http://www.openoffice.org/api/SDK/ and [[Documentation/DevGuide]]

Its recommended to use Eclipse or Netbeans to develop with OpenOffice SDK. There are plugins for booth, but they don't support C++ programming. Feel free to help adding this feature: For Eclipse visit [[OpenOffice_Eclipse_Integration]]. For Netbeans visit [[OpenOffice_NetBeans_Integration]].

Bear in mind the easier way to construct the examples of the SDK is to use the makefiles provided. If you want to start a project, begin with modifying an example of the SDK.
}}

{{Documentation/NeedsRework}}
== Installation under Windows ==
{{Documentation/Windows|

You need a compiler out of the Microsoft Visual Studio family (other compilers like MinGW have turned out to be hard to configure for OOo on Windows).
The first thing after having installed the SDK is to launch the configureWindowsNT.bat and set all the necessary directories for proper use of the SDK.
If that has been done you have already installed everything, but *wait* one very important thing you should still know of:
Every time you want to run your own code or one of the SDK examples you need to launch the setsdkenv_Windows batch file from your command shell. The title of it should now be "Shell prepared for SDK". Happy coding, compiling and building now (I tell you it's easy from now on!).
GanescuCarmen describes some problems he encounter when trying SDK examples under Windows :
“I also use the 1.1 OO version.

I had a lots of problems.
Finally I succeeded to obtain the the header files, and in VC I needed some library to be included into project and some files(uno.idl) to be added to rdb files.
It was very hard to understand what it means registry(the rdb file not the Registry itself).

I was expecting to register something in Registry but it wasn't like this.
And with the service manager I had some problems, with the port, because the connection with 8100 port was not done.
I had to modify a file and to add some code for 8100 port.

But I did it and it works now.”
}}

=== Installing with the free MS Visual C++ Toolkit 2003 ===
{{Documentation/HelpNeeded|This section needs help for update because '''MS Visual C++ Toolkit 2003''' seems no more available. Please have a look at Microsoft for the free Visual C++ tools at the moment.}}
I have installed DevCpp to have a make executable file.
I have downloaded the free Visual C++ Toolkit 2003 here :
http://www.microsoft.com/downloads/details.aspx?FamilyID=272be09d-40bb-49fd-9cb0-4bfa122fa91b&displaylang=en

and then I have installed it. '''(This link is broken.)'''

I launch first C:\openoffice\OpenOffice.org2.0_SDK\configureWindowsNT.bat
which asks any questions :
<pre>
set OO_SDK_HOME=C:\openoffice\OpenOffice.org2.0_SDK
set OFFICE_HOME=C:\Program Files\OpenOffice.org 2.0
set OO_SDK_MAKE_HOME=C:\Dev-C++\Bin
set OO_SDK_CPP_HOME=C:\Program Files\Microsoft Visual C++ Toolkit 2003\Bin
set OO_SDK_JAVA_HOME=C:\Program Files\Java\jdk1.5.0_03
</pre>

and I am ready to launch setsdkenv_windows.bat

I have modified the following file :
C:\openoffice\OpenOffice.org2.0_SDK\examples\DevelopersGuide\ProfUNO\CppBinding\office_connect.cxx
to change the port accordingly to what OOo is listening.

I have modified the makefile :
added :
<pre>
CC_INCLUDES = -I"C:\Program Files\Microsoft Visual C++ Toolkit 2003\include" \
-I"C:\openoffice\OpenOffice.org2.0_SDK\include"
</pre>

and added libraries too :

<pre>
$(OUT_BIN)/%$(EXE_EXT) : $(SAMPLE_OBJ_OUT)/%.$(OBJ_EXT)
-$(MKDIR) $(subst /,$(PS),$(@D))
-$(MKDIR) $(subst /,$(PS),$(SAMPLE_GEN_OUT))
ifeq "$(OS)" "WIN"
$(LINK) $(EXE_LINK_FLAGS) /OUT:$@ /MAP:$(SAMPLE_GEN_OUT)/$(subst $(EXE_EXT),.map,$(@F)) \
$< $(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB)\
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libcp.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libc.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\oldnames.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\kernel32.lib"
else
$(LINK) $(EXE_LINK_FLAGS) $(LINK_LIBS) -o $@ $< \
$(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB) $(STDC++LIB)
endif
</pre>
I suppose there is a more straightforward way to add these libraries with adding the corresponding include path but I am unable to do that with VC++.

I find a solution of the previous problem three weeks later. My problem comes in fact from a bug in setsdkenv_windows.bat. A little correction in the file setsdkenv_windows.bat makes it possible to avoid the makefile modifications :
Put :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "C:\Program Files\Microsoft Visual C++ Toolkit 2003\VCVARS32.bat"
</pre>

instead of :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "%OO_SDK_CPP_HOME%\VCVARS32.bat"
</pre>
I think
<pre>
%OO_SDK_CPP_HOME%\..\VCVARS32.bat
</pre>
could work too (but not checked). You can also move vcvars32.bat in %OO_SDK_CPP_HOME%
("C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin" for me).

=== Other Windows Installations descriptions ===

You can find in [http://www.oooforum.org/forum/viewtopic.phtml?t=23772 OOoForum] a post entitled Guide for develop OpenOffice apps with VC++ .net (by [[CppSDKAuthors|LarsB]])

1.Download and install OpenOffice.

2.Download and install OpenOffice SDK

3.Create a new folder inludecpp in <oo_sdk_path>

4.Open Dos console change directory to <oo_sdk_path>\windows\bin

4.1 run cppumaker with followig paramerers
<pre>
cppumaker -BUCR -O <oo_sdk_path>\includecpp <office_programm_dir>\types.rdb
</pre>
or better with
<pre>
cppumaker -Gc -BUCR -O<includes_path> <ooffice_path>\URE\misc\types.rdb <ooffice_path>\Basis\program\offapi.rdb
</pre>
in recent versions.

(Attention: If you recieve a init error, copy types.rdb into the <oo_sdk_path>\windows\bin folder!)
After that all hpp and hdl files should be created in <oo_sdk_path>\includecpp

5.Open Visual Studio and create a new Win32 Console Application.
Applay the following changes to your project.

5.1. Tools ->Options->Projects->VC++ Directories -> Include Files
Add \include directory and <oo_sdk_path>\includecpp

5.2. Tools ->Options->Projects->VC++ Directories -> Library files
Add <oo_sdk_path>\windows\lib directory

5.3. Tools ->Options->Projects->VC++ Directories -> Executable files
Add <office_programm_dir>\program directory (location where you installed the version of the OpenOffice)

5.4 Open the Project Settings

5.4.1 Change Configuration to all All Configurations (the combobox in the left corner of the window)

5.4.2 Add the additional libraries

Properties->Linker->ComandLine in the Additional Options tab the library files
isal.lib icppu.lib icppuhelper.lib isal.lib isalhelper.lib ireg.lib irmcxt.lib stlport_vc71.lib

6.(example) Add the DocumentLoader.cxx from the cpp examples of the sdk
and compile. The source should compile without errors.

INFO : If you got the following error have a look at the solution 2 postings above!
Up to now, with the steps above i got the following error, when i run the DocumentLoader example.
The error is thrown, when the prog execution reach the following line:

<pre>

Reference< XSimpleRegistry > xSimpleRegistry( ::cppu::createSimpleRegistry() );
</pre>

with error shown below :

<pre>
Error:
Window title: Microsoft Visual C++ Debug Library
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

If somebody has experience with this kind of error it will be nice if he could
post a solution. So that here is a complete little guide for OpenOffice with VC++ .NET

Regards
[[CppSDKAuthors|Lars]]

[[CppSDKAuthors|François]] has improved the complete procedure with remarks :
Following all the steps I (_francois_) encountered two problems

* first in point 4.4.2

But there I guess it's because the procedure was meant for SDK 2 and I'm using SDK 1.1
The stlport_vc71.lib which you must include is distributed with the SDK 2 in the SDK 1.1 stlport_vc7.lib
you just need to include the stlport_vc7.lib instead of stlport_vc71.lib

* second problem after successfuly compiling the DocumentLoader in Visual Studio I was getting the following error
Error:
<pre>
Window title: Microsoft Visual C++ Debug Libary
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

After going on debug in the visual studio I found the following line was responsible

<pre>
xSimpleRegistry->open( OUString( RTL_CONSTASCII_USTRINGPARAM("DocumentLoader.rdb") ), sal_True, sal_False );
</pre>

The DocumentLoader.rdb was missing ... I noticed that if I compiled the DocumentLoader exemples from command line with the makefile provided with the exemple a DocumentLoader.rdb was generated. I had a look at the Makefile I isolated the lines which seemed to generate the DocumentLoader.rdb into my Debug folder (or wherever your set your DocumentLoader.exe to be put by Visual Studio) in my Visual Studio project...

<pre>
regmerge c:\travail\DocumentLoader\debug\DocumentLoader.rdb / "C:\ooo\office\program\types.rdb"

regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c connector.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c remotebridge.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c bridgefac.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c uuresolver.uno.dll
</pre>

I launched all the above lines in the prompt shell and it worked I had my DocumentLoader.rdb in my Debug folder

I launched my exe file and it worked, great...

Now I guess I still need to figure out which *.uno.dll needs to be included for which functions used in the programm, but still it's a good start.
If anyone has any information about that (It may actualy be documented somewhere) don't hesitate)

== The Development Tools of the SDK ==

There are several development tools provided with the SDK : idlc, cppumaker, javamaker, rdbmaker, pkgchk, regcomp, regmerge, regview, xml2cmp, uno, and autodoc. You can find a short documentation on these tools at <OOo_SDK>/docs/tools.html and also in [[Documentation/DevGuide/WritingUNO/Required_Files|Developer's Guide]].

See also [[Compiler_versions_used_by_port_maintainers_and_release_engineers|Compiler versions used by port maintainers and release engineers]]

{{Template:Home_Page}}

= See also =
* [[FR/Documentation/Installation_du_SDK|French version of this chapter]].
* [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno|C++ and UNO tutorial]]
* [http://www.codeproject.com/KB/wtl/Wtl_OOo.aspx Prepare the OOo SDK]
* [http://www.oooforum.org/forum/viewtopic.phtml?t=79911&highlight= missing files in sdk]
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal

[[Category:Tutorial]]
[[Category:Cpp]]
[[Category:Uno]]

SDKInstallation

2014-07-10T21:37:00Z

Global667: /* Installation under LINUX */ add text command to download AOO and SDK

{{Documentation/Banner}}
{{Documentation/NeedsRework}}
= How to install the SDK and compile the C++ examples =

The following points are important, if you want to succeed in building C++ components and snippets:
* You need to have OpenOffice.org and OpenOffice SDK in the identical version
* You need to install the SDK into a directory other than the one of the AOO application
* It is strongly recommended to install the newest Java JDK on your system
* Make your operating system up to date

== Installation under Mac OS X ==
{{Documentation/OSX|
The text below describes the installation of the SDK 4.1.0 and OpenOffice 4.1.0 on Mac OS X 10.9.4 with Xcode 4.1.1. It would works for other Intel Mac configurations too.
* Install Xcode. You can get it from the Apple App Store. Perhaps you must be registered as Mac developer under https://developer.apple.com
* Install newest OpenOffice and the corresponding SDK from http://openoffice.apache.org/downloads.html (Choose MacOS_x86-64)
* (Optional) Install MacPorts from http://www.macports.org. You need MacPorts to install optional Unix-like software needed by the SDK.
* Test the SDK. Open a terminal and look for the SDK folder. Now type and run:
<pre>
cd <SDK_Folder>
./setsdkenv_unix # Need to run every time before you use the SDK
cd examples/cpp/DocumentLoader
make
soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager" &
make DocumentLoader.run
</pre>
If everything went fine, you should see a new document, with the content of <SDK_Folder>/examples/cpp/DocumentLoader/test.odt.

Further informations see: http://www.openoffice.org/api/SDK/ and [[Documentation/DevGuide]]

Its recommended to use Eclipse or Netbeans to develop with OpenOffice SDK. There are plugins for booth, but they don't support C++ programming. Feel free to help adding this feature: For Eclipse visit [[OpenOffice_Eclipse_Integration]]. For Netbeans visit [[OpenOffice_NetBeans_Integration]].

To work with the SDK and C++ use an editor of your choice.
}}

== Installation under LINUX ==
{{Documentation/Linux|
The text below describe the installation of the SDK 4.1.0 for OpenOffice.org 4.1.0 under Ubuntu.
* Make sure you have development tools installed:
<pre>
sudo aptitude install gcc make build-essential
</pre>
* Install newest OpenOffice and the corresponding SDK from http://openoffice.apache.org/downloads.html or type and run
<pre>
sudo aptitude install openoffice.org openoffice.org-dev openoffice.org-dev-doc
</pre>
* Test the SDK. Open a terminal and look for the SDK folder. Now type and run:
<pre>
cd <SDK_Folder>
./setsdkenv_unix # Need to run every time before you use the SDK
cd examples/cpp/DocumentLoader
make
soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager" &
make DocumentLoader.run
</pre>
If everything went fine, you should see a new document, with the content of <SDK_Folder>/examples/cpp/DocumentLoader/test.odt.

Further informations see: http://www.openoffice.org/api/SDK/ and [[Documentation/DevGuide]]

Its recommended to use Eclipse or Netbeans to develop with OpenOffice SDK. There are plugins for booth, but they don't support C++ programming. Feel free to help adding this feature: For Eclipse visit [[OpenOffice_Eclipse_Integration]]. For Netbeans visit [[OpenOffice_NetBeans_Integration]].

Bear in mind the easier way to construct the examples of the SDK is to use the makefiles provided. If you want to start a project, begin with modifying an example of the SDK.
}}

== Installation under Windows ==
{{Documentation/Windows|

You need a compiler out of the Microsoft Visual Studio family (other compilers like MinGW have turned out to be hard to configure for OOo on Windows).
The first thing after having installed the SDK is to launch the configureWindowsNT.bat and set all the necessary directories for proper use of the SDK.
If that has been done you have already installed everything, but *wait* one very important thing you should still know of:
Every time you want to run your own code or one of the SDK examples you need to launch the setsdkenv_Windows batch file from your command shell. The title of it should now be "Shell prepared for SDK". Happy coding, compiling and building now (I tell you it's easy from now on!).
GanescuCarmen describes some problems he encounter when trying SDK examples under Windows :
“I also use the 1.1 OO version.

I had a lots of problems.
Finally I succeeded to obtain the the header files, and in VC I needed some library to be included into project and some files(uno.idl) to be added to rdb files.
It was very hard to understand what it means registry(the rdb file not the Registry itself).

I was expecting to register something in Registry but it wasn't like this.
And with the service manager I had some problems, with the port, because the connection with 8100 port was not done.
I had to modify a file and to add some code for 8100 port.

But I did it and it works now.”
}}

=== Installing with the free MS Visual C++ Toolkit 2003 ===
{{Documentation/HelpNeeded|This section needs help for update because '''MS Visual C++ Toolkit 2003''' seems no more available. Please have a look at Microsoft for the free Visual C++ tools at the moment.}}
I have installed DevCpp to have a make executable file.
I have downloaded the free Visual C++ Toolkit 2003 here :
http://www.microsoft.com/downloads/details.aspx?FamilyID=272be09d-40bb-49fd-9cb0-4bfa122fa91b&displaylang=en

and then I have installed it. '''(This link is broken.)'''

I launch first C:\openoffice\OpenOffice.org2.0_SDK\configureWindowsNT.bat
which asks any questions :
<pre>
set OO_SDK_HOME=C:\openoffice\OpenOffice.org2.0_SDK
set OFFICE_HOME=C:\Program Files\OpenOffice.org 2.0
set OO_SDK_MAKE_HOME=C:\Dev-C++\Bin
set OO_SDK_CPP_HOME=C:\Program Files\Microsoft Visual C++ Toolkit 2003\Bin
set OO_SDK_JAVA_HOME=C:\Program Files\Java\jdk1.5.0_03
</pre>

and I am ready to launch setsdkenv_windows.bat

I have modified the following file :
C:\openoffice\OpenOffice.org2.0_SDK\examples\DevelopersGuide\ProfUNO\CppBinding\office_connect.cxx
to change the port accordingly to what OOo is listening.

I have modified the makefile :
added :
<pre>
CC_INCLUDES = -I"C:\Program Files\Microsoft Visual C++ Toolkit 2003\include" \
-I"C:\openoffice\OpenOffice.org2.0_SDK\include"
</pre>

and added libraries too :

<pre>
$(OUT_BIN)/%$(EXE_EXT) : $(SAMPLE_OBJ_OUT)/%.$(OBJ_EXT)
-$(MKDIR) $(subst /,$(PS),$(@D))
-$(MKDIR) $(subst /,$(PS),$(SAMPLE_GEN_OUT))
ifeq "$(OS)" "WIN"
$(LINK) $(EXE_LINK_FLAGS) /OUT:$@ /MAP:$(SAMPLE_GEN_OUT)/$(subst $(EXE_EXT),.map,$(@F)) \
$< $(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB)\
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libcp.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libc.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\oldnames.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\kernel32.lib"
else
$(LINK) $(EXE_LINK_FLAGS) $(LINK_LIBS) -o $@ $< \
$(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB) $(STDC++LIB)
endif
</pre>
I suppose there is a more straightforward way to add these libraries with adding the corresponding include path but I am unable to do that with VC++.

I find a solution of the previous problem three weeks later. My problem comes in fact from a bug in setsdkenv_windows.bat. A little correction in the file setsdkenv_windows.bat makes it possible to avoid the makefile modifications :
Put :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "C:\Program Files\Microsoft Visual C++ Toolkit 2003\VCVARS32.bat"
</pre>

instead of :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "%OO_SDK_CPP_HOME%\VCVARS32.bat"
</pre>
I think
<pre>
%OO_SDK_CPP_HOME%\..\VCVARS32.bat
</pre>
could work too (but not checked). You can also move vcvars32.bat in %OO_SDK_CPP_HOME%
("C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin" for me).

=== Other Windows Installations descriptions ===

You can find in [http://www.oooforum.org/forum/viewtopic.phtml?t=23772 OOoForum] a post entitled Guide for develop OpenOffice apps with VC++ .net (by [[CppSDKAuthors|LarsB]])

1.Download and install OpenOffice.

2.Download and install OpenOffice SDK

3.Create a new folder inludecpp in <oo_sdk_path>

4.Open Dos console change directory to <oo_sdk_path>\windows\bin

4.1 run cppumaker with followig paramerers
<pre>
cppumaker -BUCR -O <oo_sdk_path>\includecpp <office_programm_dir>\types.rdb
</pre>
or better with
<pre>
cppumaker -Gc -BUCR -O<includes_path> <ooffice_path>\URE\misc\types.rdb <ooffice_path>\Basis\program\offapi.rdb
</pre>
in recent versions.

(Attention: If you recieve a init error, copy types.rdb into the <oo_sdk_path>\windows\bin folder!)
After that all hpp and hdl files should be created in <oo_sdk_path>\includecpp

5.Open Visual Studio and create a new Win32 Console Application.
Applay the following changes to your project.

5.1. Tools ->Options->Projects->VC++ Directories -> Include Files
Add \include directory and <oo_sdk_path>\includecpp

5.2. Tools ->Options->Projects->VC++ Directories -> Library files
Add <oo_sdk_path>\windows\lib directory

5.3. Tools ->Options->Projects->VC++ Directories -> Executable files
Add <office_programm_dir>\program directory (location where you installed the version of the OpenOffice)

5.4 Open the Project Settings

5.4.1 Change Configuration to all All Configurations (the combobox in the left corner of the window)

5.4.2 Add the additional libraries

Properties->Linker->ComandLine in the Additional Options tab the library files
isal.lib icppu.lib icppuhelper.lib isal.lib isalhelper.lib ireg.lib irmcxt.lib stlport_vc71.lib

6.(example) Add the DocumentLoader.cxx from the cpp examples of the sdk
and compile. The source should compile without errors.

INFO : If you got the following error have a look at the solution 2 postings above!
Up to now, with the steps above i got the following error, when i run the DocumentLoader example.
The error is thrown, when the prog execution reach the following line:

<pre>

Reference< XSimpleRegistry > xSimpleRegistry( ::cppu::createSimpleRegistry() );
</pre>

with error shown below :

<pre>
Error:
Window title: Microsoft Visual C++ Debug Library
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

If somebody has experience with this kind of error it will be nice if he could
post a solution. So that here is a complete little guide for OpenOffice with VC++ .NET

Regards
[[CppSDKAuthors|Lars]]

[[CppSDKAuthors|François]] has improved the complete procedure with remarks :
Following all the steps I (_francois_) encountered two problems

* first in point 4.4.2

But there I guess it's because the procedure was meant for SDK 2 and I'm using SDK 1.1
The stlport_vc71.lib which you must include is distributed with the SDK 2 in the SDK 1.1 stlport_vc7.lib
you just need to include the stlport_vc7.lib instead of stlport_vc71.lib

* second problem after successfuly compiling the DocumentLoader in Visual Studio I was getting the following error
Error:
<pre>
Window title: Microsoft Visual C++ Debug Libary
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

After going on debug in the visual studio I found the following line was responsible

<pre>
xSimpleRegistry->open( OUString( RTL_CONSTASCII_USTRINGPARAM("DocumentLoader.rdb") ), sal_True, sal_False );
</pre>

The DocumentLoader.rdb was missing ... I noticed that if I compiled the DocumentLoader exemples from command line with the makefile provided with the exemple a DocumentLoader.rdb was generated. I had a look at the Makefile I isolated the lines which seemed to generate the DocumentLoader.rdb into my Debug folder (or wherever your set your DocumentLoader.exe to be put by Visual Studio) in my Visual Studio project...

<pre>
regmerge c:\travail\DocumentLoader\debug\DocumentLoader.rdb / "C:\ooo\office\program\types.rdb"

regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c connector.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c remotebridge.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c bridgefac.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c uuresolver.uno.dll
</pre>

I launched all the above lines in the prompt shell and it worked I had my DocumentLoader.rdb in my Debug folder

I launched my exe file and it worked, great...

Now I guess I still need to figure out which *.uno.dll needs to be included for which functions used in the programm, but still it's a good start.
If anyone has any information about that (It may actualy be documented somewhere) don't hesitate)

== The Development Tools of the SDK ==

There are several development tools provided with the SDK : idlc, cppumaker, javamaker, rdbmaker, pkgchk, regcomp, regmerge, regview, xml2cmp, uno, and autodoc. You can find a short documentation on these tools at <OOo_SDK>/docs/tools.html and also in [[Documentation/DevGuide/WritingUNO/Required_Files|Developer's Guide]].

See also [[Compiler_versions_used_by_port_maintainers_and_release_engineers|Compiler versions used by port maintainers and release engineers]]

{{Template:Home_Page}}

= See also =
* [[FR/Documentation/Installation_du_SDK|French version of this chapter]].
* [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno|C++ and UNO tutorial]]
* [http://www.codeproject.com/KB/wtl/Wtl_OOo.aspx Prepare the OOo SDK]
* [http://www.oooforum.org/forum/viewtopic.phtml?t=79911&highlight= missing files in sdk]
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal

[[Category:Tutorial]]
[[Category:Cpp]]
[[Category:Uno]]

SDKInstallation

2014-07-10T21:32:55Z

Global667: /* Installation under Solaris */ Delete Solaris isn't supported in AOO4

{{Documentation/Banner}}
{{Documentation/NeedsRework}}
= How to install the SDK and compile the C++ examples =

The following points are important, if you want to succeed in building C++ components and snippets:
* You need to have OpenOffice.org and OpenOffice SDK in the identical version
* You need to install the SDK into a directory other than the one of the AOO application
* It is strongly recommended to install the newest Java JDK on your system
* Make your operating system up to date

== Installation under Mac OS X ==
{{Documentation/OSX|
The text below describes the installation of the SDK 4.1.0 and OpenOffice 4.1.0 on Mac OS X 10.9.4 with Xcode 4.1.1. It would works for other Intel Mac configurations too.
* Install Xcode. You can get it from the Apple App Store. Perhaps you must be registered as Mac developer under https://developer.apple.com
* Install newest OpenOffice and the corresponding SDK from http://openoffice.apache.org/downloads.html (Choose MacOS_x86-64)
* (Optional) Install MacPorts from http://www.macports.org. You need MacPorts to install optional Unix-like software needed by the SDK.
* Test the SDK. Open a terminal and look for the SDK folder. Now type and run:
<pre>
cd <SDK_Folder>
./setsdkenv_unix # Need to run every time before you use the SDK
cd examples/cpp/DocumentLoader
make
soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager" &
make DocumentLoader.run
</pre>
If everything went fine, you should see a new document, with the content of <SDK_Folder>/examples/cpp/DocumentLoader/test.odt.

Further informations see: http://www.openoffice.org/api/SDK/ and [[Documentation/DevGuide]]

Its recommended to use Eclipse or Netbeans to develop with OpenOffice SDK. There are plugins for booth, but they don't support C++ programming. Feel free to help adding this feature: For Eclipse visit [[OpenOffice_Eclipse_Integration]]. For Netbeans visit [[OpenOffice_NetBeans_Integration]].

To work with the SDK and C++ use an editor of your choice.
}}

== Installation under LINUX ==
{{Documentation/Linux|
The text below describe the installation of the SDK 4.1.0 for OpenOffice.org 4.1.0 under Ubuntu.
* Make sure you have development tools installed:
<pre>
sudo apt-get install gcc make build-essential
</pre>
* Install newest OpenOffice and the corresponding SDK from http://openoffice.apache.org/downloads.html
* Test the SDK. Open a terminal and look for the SDK folder. Now type and run:
<pre>
cd <SDK_Folder>
./setsdkenv_unix # Need to run every time before you use the SDK
cd examples/cpp/DocumentLoader
make
soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager" &
make DocumentLoader.run
</pre>
If everything went fine, you should see a new document, with the content of <SDK_Folder>/examples/cpp/DocumentLoader/test.odt.

Further informations see: http://www.openoffice.org/api/SDK/ and [[Documentation/DevGuide]]

Its recommended to use Eclipse or Netbeans to develop with OpenOffice SDK. There are plugins for booth, but they don't support C++ programming. Feel free to help adding this feature: For Eclipse visit [[OpenOffice_Eclipse_Integration]]. For Netbeans visit [[OpenOffice_NetBeans_Integration]].

Bear in mind the easier way to construct the examples of the SDK is to use the makefiles provided. If you want to start a project, begin with modifying an example of the SDK.
}}

== Installation under Windows ==
{{Documentation/Windows|

You need a compiler out of the Microsoft Visual Studio family (other compilers like MinGW have turned out to be hard to configure for OOo on Windows).
The first thing after having installed the SDK is to launch the configureWindowsNT.bat and set all the necessary directories for proper use of the SDK.
If that has been done you have already installed everything, but *wait* one very important thing you should still know of:
Every time you want to run your own code or one of the SDK examples you need to launch the setsdkenv_Windows batch file from your command shell. The title of it should now be "Shell prepared for SDK". Happy coding, compiling and building now (I tell you it's easy from now on!).
GanescuCarmen describes some problems he encounter when trying SDK examples under Windows :
“I also use the 1.1 OO version.

I had a lots of problems.
Finally I succeeded to obtain the the header files, and in VC I needed some library to be included into project and some files(uno.idl) to be added to rdb files.
It was very hard to understand what it means registry(the rdb file not the Registry itself).

I was expecting to register something in Registry but it wasn't like this.
And with the service manager I had some problems, with the port, because the connection with 8100 port was not done.
I had to modify a file and to add some code for 8100 port.

But I did it and it works now.”
}}

=== Installing with the free MS Visual C++ Toolkit 2003 ===
{{Documentation/HelpNeeded|This section needs help for update because '''MS Visual C++ Toolkit 2003''' seems no more available. Please have a look at Microsoft for the free Visual C++ tools at the moment.}}
I have installed DevCpp to have a make executable file.
I have downloaded the free Visual C++ Toolkit 2003 here :
http://www.microsoft.com/downloads/details.aspx?FamilyID=272be09d-40bb-49fd-9cb0-4bfa122fa91b&displaylang=en

and then I have installed it. '''(This link is broken.)'''

I launch first C:\openoffice\OpenOffice.org2.0_SDK\configureWindowsNT.bat
which asks any questions :
<pre>
set OO_SDK_HOME=C:\openoffice\OpenOffice.org2.0_SDK
set OFFICE_HOME=C:\Program Files\OpenOffice.org 2.0
set OO_SDK_MAKE_HOME=C:\Dev-C++\Bin
set OO_SDK_CPP_HOME=C:\Program Files\Microsoft Visual C++ Toolkit 2003\Bin
set OO_SDK_JAVA_HOME=C:\Program Files\Java\jdk1.5.0_03
</pre>

and I am ready to launch setsdkenv_windows.bat

I have modified the following file :
C:\openoffice\OpenOffice.org2.0_SDK\examples\DevelopersGuide\ProfUNO\CppBinding\office_connect.cxx
to change the port accordingly to what OOo is listening.

I have modified the makefile :
added :
<pre>
CC_INCLUDES = -I"C:\Program Files\Microsoft Visual C++ Toolkit 2003\include" \
-I"C:\openoffice\OpenOffice.org2.0_SDK\include"
</pre>

and added libraries too :

<pre>
$(OUT_BIN)/%$(EXE_EXT) : $(SAMPLE_OBJ_OUT)/%.$(OBJ_EXT)
-$(MKDIR) $(subst /,$(PS),$(@D))
-$(MKDIR) $(subst /,$(PS),$(SAMPLE_GEN_OUT))
ifeq "$(OS)" "WIN"
$(LINK) $(EXE_LINK_FLAGS) /OUT:$@ /MAP:$(SAMPLE_GEN_OUT)/$(subst $(EXE_EXT),.map,$(@F)) \
$< $(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB)\
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libcp.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libc.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\oldnames.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\kernel32.lib"
else
$(LINK) $(EXE_LINK_FLAGS) $(LINK_LIBS) -o $@ $< \
$(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB) $(STDC++LIB)
endif
</pre>
I suppose there is a more straightforward way to add these libraries with adding the corresponding include path but I am unable to do that with VC++.

I find a solution of the previous problem three weeks later. My problem comes in fact from a bug in setsdkenv_windows.bat. A little correction in the file setsdkenv_windows.bat makes it possible to avoid the makefile modifications :
Put :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "C:\Program Files\Microsoft Visual C++ Toolkit 2003\VCVARS32.bat"
</pre>

instead of :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "%OO_SDK_CPP_HOME%\VCVARS32.bat"
</pre>
I think
<pre>
%OO_SDK_CPP_HOME%\..\VCVARS32.bat
</pre>
could work too (but not checked). You can also move vcvars32.bat in %OO_SDK_CPP_HOME%
("C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin" for me).

=== Other Windows Installations descriptions ===

You can find in [http://www.oooforum.org/forum/viewtopic.phtml?t=23772 OOoForum] a post entitled Guide for develop OpenOffice apps with VC++ .net (by [[CppSDKAuthors|LarsB]])

1.Download and install OpenOffice.

2.Download and install OpenOffice SDK

3.Create a new folder inludecpp in <oo_sdk_path>

4.Open Dos console change directory to <oo_sdk_path>\windows\bin

4.1 run cppumaker with followig paramerers
<pre>
cppumaker -BUCR -O <oo_sdk_path>\includecpp <office_programm_dir>\types.rdb
</pre>
or better with
<pre>
cppumaker -Gc -BUCR -O<includes_path> <ooffice_path>\URE\misc\types.rdb <ooffice_path>\Basis\program\offapi.rdb
</pre>
in recent versions.

(Attention: If you recieve a init error, copy types.rdb into the <oo_sdk_path>\windows\bin folder!)
After that all hpp and hdl files should be created in <oo_sdk_path>\includecpp

5.Open Visual Studio and create a new Win32 Console Application.
Applay the following changes to your project.

5.1. Tools ->Options->Projects->VC++ Directories -> Include Files
Add \include directory and <oo_sdk_path>\includecpp

5.2. Tools ->Options->Projects->VC++ Directories -> Library files
Add <oo_sdk_path>\windows\lib directory

5.3. Tools ->Options->Projects->VC++ Directories -> Executable files
Add <office_programm_dir>\program directory (location where you installed the version of the OpenOffice)

5.4 Open the Project Settings

5.4.1 Change Configuration to all All Configurations (the combobox in the left corner of the window)

5.4.2 Add the additional libraries

Properties->Linker->ComandLine in the Additional Options tab the library files
isal.lib icppu.lib icppuhelper.lib isal.lib isalhelper.lib ireg.lib irmcxt.lib stlport_vc71.lib

6.(example) Add the DocumentLoader.cxx from the cpp examples of the sdk
and compile. The source should compile without errors.

INFO : If you got the following error have a look at the solution 2 postings above!
Up to now, with the steps above i got the following error, when i run the DocumentLoader example.
The error is thrown, when the prog execution reach the following line:

<pre>

Reference< XSimpleRegistry > xSimpleRegistry( ::cppu::createSimpleRegistry() );
</pre>

with error shown below :

<pre>
Error:
Window title: Microsoft Visual C++ Debug Library
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

If somebody has experience with this kind of error it will be nice if he could
post a solution. So that here is a complete little guide for OpenOffice with VC++ .NET

Regards
[[CppSDKAuthors|Lars]]

[[CppSDKAuthors|François]] has improved the complete procedure with remarks :
Following all the steps I (_francois_) encountered two problems

* first in point 4.4.2

But there I guess it's because the procedure was meant for SDK 2 and I'm using SDK 1.1
The stlport_vc71.lib which you must include is distributed with the SDK 2 in the SDK 1.1 stlport_vc7.lib
you just need to include the stlport_vc7.lib instead of stlport_vc71.lib

* second problem after successfuly compiling the DocumentLoader in Visual Studio I was getting the following error
Error:
<pre>
Window title: Microsoft Visual C++ Debug Libary
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

After going on debug in the visual studio I found the following line was responsible

<pre>
xSimpleRegistry->open( OUString( RTL_CONSTASCII_USTRINGPARAM("DocumentLoader.rdb") ), sal_True, sal_False );
</pre>

The DocumentLoader.rdb was missing ... I noticed that if I compiled the DocumentLoader exemples from command line with the makefile provided with the exemple a DocumentLoader.rdb was generated. I had a look at the Makefile I isolated the lines which seemed to generate the DocumentLoader.rdb into my Debug folder (or wherever your set your DocumentLoader.exe to be put by Visual Studio) in my Visual Studio project...

<pre>
regmerge c:\travail\DocumentLoader\debug\DocumentLoader.rdb / "C:\ooo\office\program\types.rdb"

regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c connector.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c remotebridge.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c bridgefac.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c uuresolver.uno.dll
</pre>

I launched all the above lines in the prompt shell and it worked I had my DocumentLoader.rdb in my Debug folder

I launched my exe file and it worked, great...

Now I guess I still need to figure out which *.uno.dll needs to be included for which functions used in the programm, but still it's a good start.
If anyone has any information about that (It may actualy be documented somewhere) don't hesitate)

== The Development Tools of the SDK ==

There are several development tools provided with the SDK : idlc, cppumaker, javamaker, rdbmaker, pkgchk, regcomp, regmerge, regview, xml2cmp, uno, and autodoc. You can find a short documentation on these tools at <OOo_SDK>/docs/tools.html and also in [[Documentation/DevGuide/WritingUNO/Required_Files|Developer's Guide]].

See also [[Compiler_versions_used_by_port_maintainers_and_release_engineers|Compiler versions used by port maintainers and release engineers]]

{{Template:Home_Page}}

= See also =
* [[FR/Documentation/Installation_du_SDK|French version of this chapter]].
* [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno|C++ and UNO tutorial]]
* [http://www.codeproject.com/KB/wtl/Wtl_OOo.aspx Prepare the OOo SDK]
* [http://www.oooforum.org/forum/viewtopic.phtml?t=79911&highlight= missing files in sdk]
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal

[[Category:Tutorial]]
[[Category:Cpp]]
[[Category:Uno]]

SDKInstallation

2014-07-10T21:23:32Z

Global667: update shortening

{{Documentation/Banner}}
{{Documentation/NeedsRework}}
= How to install the SDK and compile the C++ examples =

The following points are important, if you want to succeed in building C++ components and snippets:
* You need to have OpenOffice.org and OpenOffice SDK in the identical version
* You need to install the SDK into a directory other than the one of the AOO application
* It is strongly recommended to install the newest Java JDK on your system
* Make your operating system up to date

== Installation under Mac OS X ==
{{Documentation/OSX|
The text below describes the installation of the SDK 4.1.0 and OpenOffice 4.1.0 on Mac OS X 10.9.4 with Xcode 4.1.1. It would works for other Intel Mac configurations too.
* Install Xcode. You can get it from the Apple App Store. Perhaps you must be registered as Mac developer under https://developer.apple.com
* Install newest OpenOffice and the corresponding SDK from http://openoffice.apache.org/downloads.html (Choose MacOS_x86-64)
* (Optional) Install MacPorts from http://www.macports.org. You need MacPorts to install optional Unix-like software needed by the SDK.
* Test the SDK. Open a terminal and look for the SDK folder. Now type and run:
<pre>
cd <SDK_Folder>
./setsdkenv_unix # Need to run every time before you use the SDK
cd examples/cpp/DocumentLoader
make
soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager" &
make DocumentLoader.run
</pre>
If everything went fine, you should see a new document, with the content of <SDK_Folder>/examples/cpp/DocumentLoader/test.odt.

Further informations see: http://www.openoffice.org/api/SDK/ and [[Documentation/DevGuide]]

Its recommended to use Eclipse or Netbeans to develop with OpenOffice SDK. There are plugins for booth, but they don't support C++ programming. Feel free to help adding this feature: For Eclipse visit [[OpenOffice_Eclipse_Integration]]. For Netbeans visit [[OpenOffice_NetBeans_Integration]].

To work with the SDK and C++ use an editor of your choice.
}}

== Installation under LINUX ==
{{Documentation/Linux|
The text below describe the installation of the SDK 4.1.0 for OpenOffice.org 4.1.0 under Ubuntu.
* Make sure you have development tools installed:
<pre>
sudo apt-get install gcc make build-essential
</pre>
* Install newest OpenOffice and the corresponding SDK from http://openoffice.apache.org/downloads.html
* Test the SDK. Open a terminal and look for the SDK folder. Now type and run:
<pre>
cd <SDK_Folder>
./setsdkenv_unix # Need to run every time before you use the SDK
cd examples/cpp/DocumentLoader
make
soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager" &
make DocumentLoader.run
</pre>
If everything went fine, you should see a new document, with the content of <SDK_Folder>/examples/cpp/DocumentLoader/test.odt.

Further informations see: http://www.openoffice.org/api/SDK/ and [[Documentation/DevGuide]]

Its recommended to use Eclipse or Netbeans to develop with OpenOffice SDK. There are plugins for booth, but they don't support C++ programming. Feel free to help adding this feature: For Eclipse visit [[OpenOffice_Eclipse_Integration]]. For Netbeans visit [[OpenOffice_NetBeans_Integration]].

Bear in mind the easier way to construct the examples of the SDK is to use the makefiles provided. If you want to start a project, begin with modifying an example of the SDK.
}}

== Installation under Solaris ==
{{Documentation/Linux|
The text below describe the installation of the OpenOffic.org SDK 3.1 for OpenOffice.org3.1

The Software Development Kit (SDK) works on the top of an existing Openoffice.org installation because of using the same libraries. The SDK requires an Openoffice.org installation (default installation directory for Solaris is /opt/openoffice.org/ and /opt/openoffice.org3/)

Depending on which language you wish to use, you will need either:
The Java SDK which can be obtained [http://java.sun.com/javase/downloads/index.jsp here].
Or a C++ complier (g++ 3.0.1 or higher is recommended). As well as GNU make (3.79.1 or higher) is also essential.

First download the Solaris SDK from [http://download.openoffice.org/sdk/index.html here].

Now run the install script by typing the following command. This script will prompt you for a temporary directory where it will extract the installation package. Just press enter and the package will be extracted into the directory shown in brackets (in this case /var/tmp/unpack_openofficeorg). If you wish to extract the package into a separate directory, type in the full directory path at the prompt.

<pre>
# sh OOo-SDK_3.1.1_SolarisSparc_install_en-US.sh
Select the directory in which to save the unpacked files. [/var/tmp/unpack_openofficeorg]

File is being checked for errors ...
Unpacking ...
All files have been successfully unpacked.
</pre>

Now navigate into the packages directory under the unpacked installation directory that was just created.

<pre>
# cd /var/tmp/unpack_openofficeorg/packages
</pre>

Go ahead an install the SDK package using pfexec.

<pre>
# pfexec pkgadd -d .
</pre>

To check if the installation succeeded, attempt to navigate into the sdk directory under the OpenOffic.org basis directory.
<pre>
# cd /opt/openoffice.org/basis3.1/sdk
# ls
bin/ examples/ setsdkenv_unix.csh.in
classes/ idl/ setsdkenv_unix.sh.in
config.guess include/ settings/
config.sub index.html share/
configure.pl lib/
docs/ setsdkenv_unix
</pre>

Now you are ready to use the SDK. Every time you want to use it you have to launch the setsdkenv_unix script for environment variables. Automating this is not a problem under UNIX. You can find a little complement of this chapter in <OpenOffice.org1.1_SDK>/docs/install.html

In order to use the SDK you need to first execute the setsdkevn_unx script in the <OpenOffice.org>/basis3.1/sdk directory (/opt/openoffice.org/basis3.1/sdk for me). Before you execute this script, you need to locate all of the development tools for the language you will be using. Below is a list of the tools that the script prompts for and the locations of the tools on my machine.

<pre>
OpenOffice.org3 installation = /opt/openoffice.org3
GNU make 3.79.1 or higher = /usr/bin
C++ compiler (g++ 3.0.1 or higher) = /usr/bin
Zip = /usr/bin
Java = /usr/jdk/latest/
</pre>

Input the paths to your development tools when prompted.

You are now ready to use the OpenOffice SDK
}}

== Installation under Windows ==
{{Documentation/Windows|

You need a compiler out of the Microsoft Visual Studio family (other compilers like MinGW have turned out to be hard to configure for OOo on Windows).
The first thing after having installed the SDK is to launch the configureWindowsNT.bat and set all the necessary directories for proper use of the SDK.
If that has been done you have already installed everything, but *wait* one very important thing you should still know of:
Every time you want to run your own code or one of the SDK examples you need to launch the setsdkenv_Windows batch file from your command shell. The title of it should now be "Shell prepared for SDK". Happy coding, compiling and building now (I tell you it's easy from now on!).
GanescuCarmen describes some problems he encounter when trying SDK examples under Windows :
“I also use the 1.1 OO version.

I had a lots of problems.
Finally I succeeded to obtain the the header files, and in VC I needed some library to be included into project and some files(uno.idl) to be added to rdb files.
It was very hard to understand what it means registry(the rdb file not the Registry itself).

I was expecting to register something in Registry but it wasn't like this.
And with the service manager I had some problems, with the port, because the connection with 8100 port was not done.
I had to modify a file and to add some code for 8100 port.

But I did it and it works now.”
}}

=== Installing with the free MS Visual C++ Toolkit 2003 ===
{{Documentation/HelpNeeded|This section needs help for update because '''MS Visual C++ Toolkit 2003''' seems no more available. Please have a look at Microsoft for the free Visual C++ tools at the moment.}}
I have installed DevCpp to have a make executable file.
I have downloaded the free Visual C++ Toolkit 2003 here :
http://www.microsoft.com/downloads/details.aspx?FamilyID=272be09d-40bb-49fd-9cb0-4bfa122fa91b&displaylang=en

and then I have installed it. '''(This link is broken.)'''

I launch first C:\openoffice\OpenOffice.org2.0_SDK\configureWindowsNT.bat
which asks any questions :
<pre>
set OO_SDK_HOME=C:\openoffice\OpenOffice.org2.0_SDK
set OFFICE_HOME=C:\Program Files\OpenOffice.org 2.0
set OO_SDK_MAKE_HOME=C:\Dev-C++\Bin
set OO_SDK_CPP_HOME=C:\Program Files\Microsoft Visual C++ Toolkit 2003\Bin
set OO_SDK_JAVA_HOME=C:\Program Files\Java\jdk1.5.0_03
</pre>

and I am ready to launch setsdkenv_windows.bat

I have modified the following file :
C:\openoffice\OpenOffice.org2.0_SDK\examples\DevelopersGuide\ProfUNO\CppBinding\office_connect.cxx
to change the port accordingly to what OOo is listening.

I have modified the makefile :
added :
<pre>
CC_INCLUDES = -I"C:\Program Files\Microsoft Visual C++ Toolkit 2003\include" \
-I"C:\openoffice\OpenOffice.org2.0_SDK\include"
</pre>

and added libraries too :

<pre>
$(OUT_BIN)/%$(EXE_EXT) : $(SAMPLE_OBJ_OUT)/%.$(OBJ_EXT)
-$(MKDIR) $(subst /,$(PS),$(@D))
-$(MKDIR) $(subst /,$(PS),$(SAMPLE_GEN_OUT))
ifeq "$(OS)" "WIN"
$(LINK) $(EXE_LINK_FLAGS) /OUT:$@ /MAP:$(SAMPLE_GEN_OUT)/$(subst $(EXE_EXT),.map,$(@F)) \
$< $(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB)\
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libcp.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libc.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\oldnames.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\kernel32.lib"
else
$(LINK) $(EXE_LINK_FLAGS) $(LINK_LIBS) -o $@ $< \
$(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB) $(STDC++LIB)
endif
</pre>
I suppose there is a more straightforward way to add these libraries with adding the corresponding include path but I am unable to do that with VC++.

I find a solution of the previous problem three weeks later. My problem comes in fact from a bug in setsdkenv_windows.bat. A little correction in the file setsdkenv_windows.bat makes it possible to avoid the makefile modifications :
Put :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "C:\Program Files\Microsoft Visual C++ Toolkit 2003\VCVARS32.bat"
</pre>

instead of :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "%OO_SDK_CPP_HOME%\VCVARS32.bat"
</pre>
I think
<pre>
%OO_SDK_CPP_HOME%\..\VCVARS32.bat
</pre>
could work too (but not checked). You can also move vcvars32.bat in %OO_SDK_CPP_HOME%
("C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin" for me).

=== Other Windows Installations descriptions ===

You can find in [http://www.oooforum.org/forum/viewtopic.phtml?t=23772 OOoForum] a post entitled Guide for develop OpenOffice apps with VC++ .net (by [[CppSDKAuthors|LarsB]])

1.Download and install OpenOffice.

2.Download and install OpenOffice SDK

3.Create a new folder inludecpp in <oo_sdk_path>

4.Open Dos console change directory to <oo_sdk_path>\windows\bin

4.1 run cppumaker with followig paramerers
<pre>
cppumaker -BUCR -O <oo_sdk_path>\includecpp <office_programm_dir>\types.rdb
</pre>
or better with
<pre>
cppumaker -Gc -BUCR -O<includes_path> <ooffice_path>\URE\misc\types.rdb <ooffice_path>\Basis\program\offapi.rdb
</pre>
in recent versions.

(Attention: If you recieve a init error, copy types.rdb into the <oo_sdk_path>\windows\bin folder!)
After that all hpp and hdl files should be created in <oo_sdk_path>\includecpp

5.Open Visual Studio and create a new Win32 Console Application.
Applay the following changes to your project.

5.1. Tools ->Options->Projects->VC++ Directories -> Include Files
Add \include directory and <oo_sdk_path>\includecpp

5.2. Tools ->Options->Projects->VC++ Directories -> Library files
Add <oo_sdk_path>\windows\lib directory

5.3. Tools ->Options->Projects->VC++ Directories -> Executable files
Add <office_programm_dir>\program directory (location where you installed the version of the OpenOffice)

5.4 Open the Project Settings

5.4.1 Change Configuration to all All Configurations (the combobox in the left corner of the window)

5.4.2 Add the additional libraries

Properties->Linker->ComandLine in the Additional Options tab the library files
isal.lib icppu.lib icppuhelper.lib isal.lib isalhelper.lib ireg.lib irmcxt.lib stlport_vc71.lib

6.(example) Add the DocumentLoader.cxx from the cpp examples of the sdk
and compile. The source should compile without errors.

INFO : If you got the following error have a look at the solution 2 postings above!
Up to now, with the steps above i got the following error, when i run the DocumentLoader example.
The error is thrown, when the prog execution reach the following line:

<pre>

Reference< XSimpleRegistry > xSimpleRegistry( ::cppu::createSimpleRegistry() );
</pre>

with error shown below :

<pre>
Error:
Window title: Microsoft Visual C++ Debug Library
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

If somebody has experience with this kind of error it will be nice if he could
post a solution. So that here is a complete little guide for OpenOffice with VC++ .NET

Regards
[[CppSDKAuthors|Lars]]

[[CppSDKAuthors|François]] has improved the complete procedure with remarks :
Following all the steps I (_francois_) encountered two problems

* first in point 4.4.2

But there I guess it's because the procedure was meant for SDK 2 and I'm using SDK 1.1
The stlport_vc71.lib which you must include is distributed with the SDK 2 in the SDK 1.1 stlport_vc7.lib
you just need to include the stlport_vc7.lib instead of stlport_vc71.lib

* second problem after successfuly compiling the DocumentLoader in Visual Studio I was getting the following error
Error:
<pre>
Window title: Microsoft Visual C++ Debug Libary
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

After going on debug in the visual studio I found the following line was responsible

<pre>
xSimpleRegistry->open( OUString( RTL_CONSTASCII_USTRINGPARAM("DocumentLoader.rdb") ), sal_True, sal_False );
</pre>

The DocumentLoader.rdb was missing ... I noticed that if I compiled the DocumentLoader exemples from command line with the makefile provided with the exemple a DocumentLoader.rdb was generated. I had a look at the Makefile I isolated the lines which seemed to generate the DocumentLoader.rdb into my Debug folder (or wherever your set your DocumentLoader.exe to be put by Visual Studio) in my Visual Studio project...

<pre>
regmerge c:\travail\DocumentLoader\debug\DocumentLoader.rdb / "C:\ooo\office\program\types.rdb"

regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c connector.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c remotebridge.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c bridgefac.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c uuresolver.uno.dll
</pre>

I launched all the above lines in the prompt shell and it worked I had my DocumentLoader.rdb in my Debug folder

I launched my exe file and it worked, great...

Now I guess I still need to figure out which *.uno.dll needs to be included for which functions used in the programm, but still it's a good start.
If anyone has any information about that (It may actualy be documented somewhere) don't hesitate)

== The Development Tools of the SDK ==

There are several development tools provided with the SDK : idlc, cppumaker, javamaker, rdbmaker, pkgchk, regcomp, regmerge, regview, xml2cmp, uno, and autodoc. You can find a short documentation on these tools at <OOo_SDK>/docs/tools.html and also in [[Documentation/DevGuide/WritingUNO/Required_Files|Developer's Guide]].

See also [[Compiler_versions_used_by_port_maintainers_and_release_engineers|Compiler versions used by port maintainers and release engineers]]

{{Template:Home_Page}}

= See also =
* [[FR/Documentation/Installation_du_SDK|French version of this chapter]].
* [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno|C++ and UNO tutorial]]
* [http://www.codeproject.com/KB/wtl/Wtl_OOo.aspx Prepare the OOo SDK]
* [http://www.oooforum.org/forum/viewtopic.phtml?t=79911&highlight= missing files in sdk]
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal

[[Category:Tutorial]]
[[Category:Cpp]]
[[Category:Uno]]

SDKInstallation

2014-07-10T21:15:58Z

Global667: clean linux part, mac os additions (checkpoint save)

{{Documentation/Banner}}
{{Documentation/NeedsRework}}
= How to install the SDK and compile the C++ examples =

The following points are important, if you want to succeed in building C++ components and snippets:
* You need to have OpenOffice.org and OpenOffice SDK in the identical version
* You need to install the SDK into a directory other than the one of the AOO application
* It is strongly recommended to install the newest Java JDK on your system
* Make your operating system up to date

== Installation under Mac OS X ==
{{Documentation/OSX|
The text below describes the installation of the SDK 4.1.0 and OpenOffice 4.1.0 on Mac OS X 10.9.4 with Xcode 4.1.1. It would works for other Intel Mac configurations too.
* Install Xcode. You can get it from the Apple App Store. Perhaps you must be registered as Mac developer under https://developer.apple.com
* Install newest OpenOffice and the corresponding SDK from http://openoffice.apache.org/downloads.html (Choose MacOS_x86-64)
* (Optional) Install MacPorts from http://www.macports.org. You need MacPorts to install optional Unix-like software needed by the SDK.
* Test the SDK. Open a terminal and look for the SDK folder. Now type and run:
<pre>
cd <SDK_Folder>
./setsdkenv_unix # Need to run every time before you use the SDK
cd examples/cpp/DocumentLoader
make
soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager" &
make DocumentLoader.run
</pre>
If everything went fine, you should see a new document, with the content of <SDK_Folder>/examples/cpp/DocumentLoader/test.odt.

Further informations see: http://www.openoffice.org/api/SDK/ and [[Documentation/DevGuide]]

Its recommended to use Eclipse or Netbeans to develop with OpenOffice SDK. There are plugins for booth, but they don't support C++ programming. Feel free to help adding this feature: For Eclipse visit [[OpenOffice_Eclipse_Integration]]. For Netbeans visit [[OpenOffice_NetBeans_Integration]].

To work with the SDK and C++ use an editor of your choice.
}}

== Installation under LINUX ==
{{Documentation/Linux|
The text below describe the installation of the SDK 4.1.0 for OpenOffice.org 4.1.0 under Ubuntu.
* Make sure you have development tools installed:
<pre>
sudo apt-get install gcc make build-essential
</pre>
* Install newest OpenOffice and the corresponding SDK from http://openoffice.apache.org/downloads.html
* Test the SDK. Open a terminal and look for the SDK folder. Now type and run:
<pre>
cd <SDK_Folder>
./setsdkenv_unix # Need to run every time before you use the SDK
cd examples/cpp/DocumentLoader
make
soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager" &
make DocumentLoader.run
</pre>
If everything went fine, you should see a new document, with the content of <SDK_Folder>/examples/cpp/DocumentLoader/test.odt.

Further informations see: http://www.openoffice.org/api/SDK/ and [[Documentation/DevGuide]]

Its recommended to use Eclipse or Netbeans to develop with OpenOffice SDK. There are plugins for booth, but they don't support C++ programming. Feel free to help adding this feature: For Eclipse visit [[OpenOffice_Eclipse_Integration]]. For Netbeans visit [[OpenOffice_NetBeans_Integration]].

Bear in mind the easier way to construct the examples of the SDK is to use the makefiles provided. When you are a beginner with the SDK you always underestimate important steps : for example the registry step discussed later. I estimate to have understand something when I am able to construct it starting with nothing (but skills). In the case of SDK this will take me a long time (and probably will not be finished). Then I can give you an advice : if you want to start a project, begin with modifying an example of the SDK.
}}

== Installation under Solaris ==
{{Documentation/Linux|
The text below describe the installation of the OpenOffic.org SDK 3.1 for OpenOffice.org3.1

The Software Development Kit (SDK) works on the top of an existing Openoffice.org installation because of using the same libraries. The SDK requires an Openoffice.org installation (default installation directory for Solaris is /opt/openoffice.org/ and /opt/openoffice.org3/)

Depending on which language you wish to use, you will need either:
The Java SDK which can be obtained [http://java.sun.com/javase/downloads/index.jsp here].
Or a C++ complier (g++ 3.0.1 or higher is recommended). As well as GNU make (3.79.1 or higher) is also essential.

First download the Solaris SDK from [http://download.openoffice.org/sdk/index.html here].

Now run the install script by typing the following command. This script will prompt you for a temporary directory where it will extract the installation package. Just press enter and the package will be extracted into the directory shown in brackets (in this case /var/tmp/unpack_openofficeorg). If you wish to extract the package into a separate directory, type in the full directory path at the prompt.

<pre>
# sh OOo-SDK_3.1.1_SolarisSparc_install_en-US.sh
Select the directory in which to save the unpacked files. [/var/tmp/unpack_openofficeorg]

File is being checked for errors ...
Unpacking ...
All files have been successfully unpacked.
</pre>

Now navigate into the packages directory under the unpacked installation directory that was just created.

<pre>
# cd /var/tmp/unpack_openofficeorg/packages
</pre>

Go ahead an install the SDK package using pfexec.

<pre>
# pfexec pkgadd -d .
</pre>

To check if the installation succeeded, attempt to navigate into the sdk directory under the OpenOffic.org basis directory.
<pre>
# cd /opt/openoffice.org/basis3.1/sdk
# ls
bin/ examples/ setsdkenv_unix.csh.in
classes/ idl/ setsdkenv_unix.sh.in
config.guess include/ settings/
config.sub index.html share/
configure.pl lib/
docs/ setsdkenv_unix
</pre>

Now you are ready to use the SDK. Every time you want to use it you have to launch the setsdkenv_unix script for environment variables. Automating this is not a problem under UNIX. You can find a little complement of this chapter in <OpenOffice.org1.1_SDK>/docs/install.html

In order to use the SDK you need to first execute the setsdkevn_unx script in the <OpenOffice.org>/basis3.1/sdk directory (/opt/openoffice.org/basis3.1/sdk for me). Before you execute this script, you need to locate all of the development tools for the language you will be using. Below is a list of the tools that the script prompts for and the locations of the tools on my machine.

<pre>
OpenOffice.org3 installation = /opt/openoffice.org3
GNU make 3.79.1 or higher = /usr/bin
C++ compiler (g++ 3.0.1 or higher) = /usr/bin
Zip = /usr/bin
Java = /usr/jdk/latest/
</pre>

Input the paths to your development tools when prompted.

You are now ready to use the OpenOffice SDK
}}

== Installation under Windows ==
{{Documentation/Windows|

You need a compiler out of the Microsoft Visual Studio family (other compilers like MinGW have turned out to be hard to configure for OOo on Windows).
The first thing after having installed the SDK is to launch the configureWindowsNT.bat and set all the necessary directories for proper use of the SDK.
If that has been done you have already installed everything, but *wait* one very important thing you should still know of:
Every time you want to run your own code or one of the SDK examples you need to launch the setsdkenv_Windows batch file from your command shell. The title of it should now be "Shell prepared for SDK". Happy coding, compiling and building now (I tell you it's easy from now on!).
GanescuCarmen describes some problems he encounter when trying SDK examples under Windows :
“I also use the 1.1 OO version.

I had a lots of problems.
Finally I succeeded to obtain the the header files, and in VC I needed some library to be included into project and some files(uno.idl) to be added to rdb files.
It was very hard to understand what it means registry(the rdb file not the Registry itself).

I was expecting to register something in Registry but it wasn't like this.
And with the service manager I had some problems, with the port, because the connection with 8100 port was not done.
I had to modify a file and to add some code for 8100 port.

But I did it and it works now.”
}}

=== Installing with the free MS Visual C++ Toolkit 2003 ===
{{Documentation/HelpNeeded|This section needs help for update because '''MS Visual C++ Toolkit 2003''' seems no more available. Please have a look at Microsoft for the free Visual C++ tools at the moment.}}
I have installed DevCpp to have a make executable file.
I have downloaded the free Visual C++ Toolkit 2003 here :
http://www.microsoft.com/downloads/details.aspx?FamilyID=272be09d-40bb-49fd-9cb0-4bfa122fa91b&displaylang=en

and then I have installed it. '''(This link is broken.)'''

I launch first C:\openoffice\OpenOffice.org2.0_SDK\configureWindowsNT.bat
which asks any questions :
<pre>
set OO_SDK_HOME=C:\openoffice\OpenOffice.org2.0_SDK
set OFFICE_HOME=C:\Program Files\OpenOffice.org 2.0
set OO_SDK_MAKE_HOME=C:\Dev-C++\Bin
set OO_SDK_CPP_HOME=C:\Program Files\Microsoft Visual C++ Toolkit 2003\Bin
set OO_SDK_JAVA_HOME=C:\Program Files\Java\jdk1.5.0_03
</pre>

and I am ready to launch setsdkenv_windows.bat

I have modified the following file :
C:\openoffice\OpenOffice.org2.0_SDK\examples\DevelopersGuide\ProfUNO\CppBinding\office_connect.cxx
to change the port accordingly to what OOo is listening.

I have modified the makefile :
added :
<pre>
CC_INCLUDES = -I"C:\Program Files\Microsoft Visual C++ Toolkit 2003\include" \
-I"C:\openoffice\OpenOffice.org2.0_SDK\include"
</pre>

and added libraries too :

<pre>
$(OUT_BIN)/%$(EXE_EXT) : $(SAMPLE_OBJ_OUT)/%.$(OBJ_EXT)
-$(MKDIR) $(subst /,$(PS),$(@D))
-$(MKDIR) $(subst /,$(PS),$(SAMPLE_GEN_OUT))
ifeq "$(OS)" "WIN"
$(LINK) $(EXE_LINK_FLAGS) /OUT:$@ /MAP:$(SAMPLE_GEN_OUT)/$(subst $(EXE_EXT),.map,$(@F)) \
$< $(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB)\
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libcp.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libc.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\oldnames.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\kernel32.lib"
else
$(LINK) $(EXE_LINK_FLAGS) $(LINK_LIBS) -o $@ $< \
$(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB) $(STDC++LIB)
endif
</pre>
I suppose there is a more straightforward way to add these libraries with adding the corresponding include path but I am unable to do that with VC++.

I find a solution of the previous problem three weeks later. My problem comes in fact from a bug in setsdkenv_windows.bat. A little correction in the file setsdkenv_windows.bat makes it possible to avoid the makefile modifications :
Put :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "C:\Program Files\Microsoft Visual C++ Toolkit 2003\VCVARS32.bat"
</pre>

instead of :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "%OO_SDK_CPP_HOME%\VCVARS32.bat"
</pre>
I think
<pre>
%OO_SDK_CPP_HOME%\..\VCVARS32.bat
</pre>
could work too (but not checked). You can also move vcvars32.bat in %OO_SDK_CPP_HOME%
("C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin" for me).

=== Other Windows Installations descriptions ===

You can find in [http://www.oooforum.org/forum/viewtopic.phtml?t=23772 OOoForum] a post entitled Guide for develop OpenOffice apps with VC++ .net (by [[CppSDKAuthors|LarsB]])

1.Download and install OpenOffice.

2.Download and install OpenOffice SDK

3.Create a new folder inludecpp in <oo_sdk_path>

4.Open Dos console change directory to <oo_sdk_path>\windows\bin

4.1 run cppumaker with followig paramerers
<pre>
cppumaker -BUCR -O <oo_sdk_path>\includecpp <office_programm_dir>\types.rdb
</pre>
or better with
<pre>
cppumaker -Gc -BUCR -O<includes_path> <ooffice_path>\URE\misc\types.rdb <ooffice_path>\Basis\program\offapi.rdb
</pre>
in recent versions.

(Attention: If you recieve a init error, copy types.rdb into the <oo_sdk_path>\windows\bin folder!)
After that all hpp and hdl files should be created in <oo_sdk_path>\includecpp

5.Open Visual Studio and create a new Win32 Console Application.
Applay the following changes to your project.

5.1. Tools ->Options->Projects->VC++ Directories -> Include Files
Add \include directory and <oo_sdk_path>\includecpp

5.2. Tools ->Options->Projects->VC++ Directories -> Library files
Add <oo_sdk_path>\windows\lib directory

5.3. Tools ->Options->Projects->VC++ Directories -> Executable files
Add <office_programm_dir>\program directory (location where you installed the version of the OpenOffice)

5.4 Open the Project Settings

5.4.1 Change Configuration to all All Configurations (the combobox in the left corner of the window)

5.4.2 Add the additional libraries

Properties->Linker->ComandLine in the Additional Options tab the library files
isal.lib icppu.lib icppuhelper.lib isal.lib isalhelper.lib ireg.lib irmcxt.lib stlport_vc71.lib

6.(example) Add the DocumentLoader.cxx from the cpp examples of the sdk
and compile. The source should compile without errors.

INFO : If you got the following error have a look at the solution 2 postings above!
Up to now, with the steps above i got the following error, when i run the DocumentLoader example.
The error is thrown, when the prog execution reach the following line:

<pre>

Reference< XSimpleRegistry > xSimpleRegistry( ::cppu::createSimpleRegistry() );
</pre>

with error shown below :

<pre>
Error:
Window title: Microsoft Visual C++ Debug Library
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

If somebody has experience with this kind of error it will be nice if he could
post a solution. So that here is a complete little guide for OpenOffice with VC++ .NET

Regards
[[CppSDKAuthors|Lars]]

[[CppSDKAuthors|François]] has improved the complete procedure with remarks :
Following all the steps I (_francois_) encountered two problems

* first in point 4.4.2

But there I guess it's because the procedure was meant for SDK 2 and I'm using SDK 1.1
The stlport_vc71.lib which you must include is distributed with the SDK 2 in the SDK 1.1 stlport_vc7.lib
you just need to include the stlport_vc7.lib instead of stlport_vc71.lib

* second problem after successfuly compiling the DocumentLoader in Visual Studio I was getting the following error
Error:
<pre>
Window title: Microsoft Visual C++ Debug Libary
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

After going on debug in the visual studio I found the following line was responsible

<pre>
xSimpleRegistry->open( OUString( RTL_CONSTASCII_USTRINGPARAM("DocumentLoader.rdb") ), sal_True, sal_False );
</pre>

The DocumentLoader.rdb was missing ... I noticed that if I compiled the DocumentLoader exemples from command line with the makefile provided with the exemple a DocumentLoader.rdb was generated. I had a look at the Makefile I isolated the lines which seemed to generate the DocumentLoader.rdb into my Debug folder (or wherever your set your DocumentLoader.exe to be put by Visual Studio) in my Visual Studio project...

<pre>
regmerge c:\travail\DocumentLoader\debug\DocumentLoader.rdb / "C:\ooo\office\program\types.rdb"

regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c connector.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c remotebridge.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c bridgefac.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c uuresolver.uno.dll
</pre>

I launched all the above lines in the prompt shell and it worked I had my DocumentLoader.rdb in my Debug folder

I launched my exe file and it worked, great...

Now I guess I still need to figure out which *.uno.dll needs to be included for which functions used in the programm, but still it's a good start.
If anyone has any information about that (It may actualy be documented somewhere) don't hesitate)

== The Development Tools of the SDK ==

There are several development tools provided with the SDK : idlc, cppumaker, javamaker, rdbmaker, pkgchk, regcomp, regmerge, regview, xml2cmp, uno, and autodoc. You can find a short documentation on these tools at <OOo_SDK>/docs/tools.html and also in [[Documentation/DevGuide/WritingUNO/Required_Files|Developer's Guide]].

See also [[Compiler_versions_used_by_port_maintainers_and_release_engineers|Compiler versions used by port maintainers and release engineers]]

{{Template:Home_Page}}

= See also =
* [[FR/Documentation/Installation_du_SDK|French version of this chapter]].
* [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno|C++ and UNO tutorial]]
* [http://www.codeproject.com/KB/wtl/Wtl_OOo.aspx Prepare the OOo SDK]
* [http://www.oooforum.org/forum/viewtopic.phtml?t=79911&highlight= missing files in sdk]
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal

[[Category:Tutorial]]
[[Category:Cpp]]
[[Category:Uno]]

SDKInstallation

2014-07-10T20:46:11Z

Global667: /* How to install the SDK and compile the C++ examples */ additions, expansions

{{Documentation/Banner}}
{{Documentation/NeedsRework}}
= How to install the SDK and compile the C++ examples =

The following points are important, if you want to succeed in building C++ components and snippets:
* You need to have OpenOffice.org and OpenOffice SDK in the identical version
* You need to install the SDK into a directory other than the one of the AOO application
* It is strongly recommended to install the newest Java JDK on your system
* Make your operating system up to date

== Installation under Mac OS X ==
{{Documentation/OSX|
The text below describes the installation of the SDK 4.1.0 and OpenOffice 4.1.0 on Mac OS X 10.9.4 with Xcode 4.1.1. It would works for other Intel Mac configurations too.
* Install Xcode. You can get it from the Apple App Store. Perhaps you must be registered as Mac developer under https://developer.apple.com
* Install newest OpenOffice and the corresponding SDK from http://openoffice.apache.org/downloads.html (Choose MacOS_x86-64)
* (Optional) Install MacPorts from http://www.macports.org. You need MacPorts to install optional Unix-like software needed by the SDK.
* Test the SDK. Open a terminal and look for the SDK folder. Now type and run:
<pre>
cd <SDK_Folder>
./setsdkenv_unix # Need to run every time before you use the SDK
cd examples/cpp/DocumentLoader
make
soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager" &
make DocumentLoader.run
</pre>
If everything went fine, you should see a new document, with the content of <SDK_Folder>/examples/cpp/DocumentLoader/test.odt.

Further informations see: http://www.openoffice.org/api/SDK/ and [[Documentation/DevGuide]]

Its recommended to use Eclipse or Netbeans to develop with OpenOffice SDK. There are plugins for booth.
For Eclipse visit [[OpenOffice_Eclipse_Integration]].
For Netbeans visit [[OpenOffice_NetBeans_Integration]].
}}

== Installation under LINUX ==
{{Documentation/Linux|
The text below describe the installation of the SDK 1.1.0 for OpenOffice.org1.1.0

The Software Development Kit (SDK) works on the top of an existing Openoffice.org installation because of using the same libraries. The SDK requires an Openoffice.org installation.
Even if you don't plan to use Java it is strongly recommended to install the JDK (1.4.1_01 or higher for OOo 1.1 SDK)
Of course a C++ compiler is needed (3.0.1 or higher). GNU make (3.79.1 or higher) is also essential.
When ready, launch :
<pre>
tar xzvf Ooo_1.1.0_LinuxIntel_sdk.tar.gz
</pre>

and go to the new created directory (in this example OpenOffice.org1.1_SDK) and launch the configure script which asks you relevant directories. We give here among others :
* where is your OpenOffice.org installed ? (for me /usr/lib/openoffice : noted <Ooo> later)
* Where is your Java SDK installed ? (for me /usr/java/j2sdk1.4.2_04)

Now you are ready to use the SDK. Every time you want to use it you have to launch the setsdkenv_unix script for environment variables. Automating this is not a problem under UNIX.

From now on, we will always note the SDK directory installation as : <OpenOffice.org1.1_SDK>. Please don't confuse with <Ooo> which is the openoffice.org /program/ directory.

You can find a little complement of this chapter in <OpenOffice.org1.1_SDK>/docs/install.html

The OOo2.0SDK installation is done also by launching the setsdkenv_unix script but asking more information :
<pre>
************************************************************************
*
* SDK environment is prepared for Linux
*
* SDK = /home/smoutou/openoffice.org2.0_sdk
* Office = /opt/openoffice.org2.0
* URE =
* Make = /usr/bin
* Zip = /usr/bin
* C++ Compiler = /usr/bin
* Java = /usr/java/j2sdk1.4.2_04
* Special Output directory = /home/smoutou
* Auto deployment = YES
*
************************************************************************
</pre>
If you want to check the Cpp examples, you have to launch first (as mentioned before)
<pre>
./setsdkenv_unix
</pre>
in your shell and then
<pre>
<Ooo>/program/soffice "-accept=socket,host=localhost,port=8100;urp;StarOffice.ServiceManager"
</pre>
For Openoffice.org 2.x, run instead:
<pre>
<Ooo>/program/soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager"
</pre>
Now Openoffice.org is listening on UNO connections through the network (here from localhost only).
We are ready to compile our first example and to check if it works correctly. For that we go in
<OpenOffice.org1.1_SDK>/examples/cpp/DocumentLoader directory.
<pre>
make
</pre>
will compile the example, and
<pre>
make DocumentLoader.run
</pre>
will launch the example. This example only load a Ooowriter's file (test.sxw) provided with the SDK.

Bear in mind the easier way to construct the examples of the SDK is to use the makefiles provided. When you are a beginner with the SDK you always underestimate important steps : for example the registry step discussed later. I estimate to have understand something when I am able to construct it starting with nothing (but skills). In the case of SDK this will take me a long time (and probably will not be finished). Then I can give you an advice : if you want to start a project, begin with modifying an example of the SDK.

Other SDK's examples are discussed later, but you can have a look to :

*[[Counter_Example|Counter example]]

}}

== Installation under Solaris ==
{{Documentation/Linux|
The text below describe the installation of the OpenOffic.org SDK 3.1 for OpenOffice.org3.1

The Software Development Kit (SDK) works on the top of an existing Openoffice.org installation because of using the same libraries. The SDK requires an Openoffice.org installation (default installation directory for Solaris is /opt/openoffice.org/ and /opt/openoffice.org3/)

Depending on which language you wish to use, you will need either:
The Java SDK which can be obtained [http://java.sun.com/javase/downloads/index.jsp here].
Or a C++ complier (g++ 3.0.1 or higher is recommended). As well as GNU make (3.79.1 or higher) is also essential.

First download the Solaris SDK from [http://download.openoffice.org/sdk/index.html here].

Now run the install script by typing the following command. This script will prompt you for a temporary directory where it will extract the installation package. Just press enter and the package will be extracted into the directory shown in brackets (in this case /var/tmp/unpack_openofficeorg). If you wish to extract the package into a separate directory, type in the full directory path at the prompt.

<pre>
# sh OOo-SDK_3.1.1_SolarisSparc_install_en-US.sh
Select the directory in which to save the unpacked files. [/var/tmp/unpack_openofficeorg]

File is being checked for errors ...
Unpacking ...
All files have been successfully unpacked.
</pre>

Now navigate into the packages directory under the unpacked installation directory that was just created.

<pre>
# cd /var/tmp/unpack_openofficeorg/packages
</pre>

Go ahead an install the SDK package using pfexec.

<pre>
# pfexec pkgadd -d .
</pre>

To check if the installation succeeded, attempt to navigate into the sdk directory under the OpenOffic.org basis directory.
<pre>
# cd /opt/openoffice.org/basis3.1/sdk
# ls
bin/ examples/ setsdkenv_unix.csh.in
classes/ idl/ setsdkenv_unix.sh.in
config.guess include/ settings/
config.sub index.html share/
configure.pl lib/
docs/ setsdkenv_unix
</pre>

Now you are ready to use the SDK. Every time you want to use it you have to launch the setsdkenv_unix script for environment variables. Automating this is not a problem under UNIX. You can find a little complement of this chapter in <OpenOffice.org1.1_SDK>/docs/install.html

In order to use the SDK you need to first execute the setsdkevn_unx script in the <OpenOffice.org>/basis3.1/sdk directory (/opt/openoffice.org/basis3.1/sdk for me). Before you execute this script, you need to locate all of the development tools for the language you will be using. Below is a list of the tools that the script prompts for and the locations of the tools on my machine.

<pre>
OpenOffice.org3 installation = /opt/openoffice.org3
GNU make 3.79.1 or higher = /usr/bin
C++ compiler (g++ 3.0.1 or higher) = /usr/bin
Zip = /usr/bin
Java = /usr/jdk/latest/
</pre>

Input the paths to your development tools when prompted.

You are now ready to use the OpenOffice SDK
}}

== Installation under Windows ==
{{Documentation/Windows|

You need a compiler out of the Microsoft Visual Studio family (other compilers like MinGW have turned out to be hard to configure for OOo on Windows).
The first thing after having installed the SDK is to launch the configureWindowsNT.bat and set all the necessary directories for proper use of the SDK.
If that has been done you have already installed everything, but *wait* one very important thing you should still know of:
Every time you want to run your own code or one of the SDK examples you need to launch the setsdkenv_Windows batch file from your command shell. The title of it should now be "Shell prepared for SDK". Happy coding, compiling and building now (I tell you it's easy from now on!).
GanescuCarmen describes some problems he encounter when trying SDK examples under Windows :
“I also use the 1.1 OO version.

I had a lots of problems.
Finally I succeeded to obtain the the header files, and in VC I needed some library to be included into project and some files(uno.idl) to be added to rdb files.
It was very hard to understand what it means registry(the rdb file not the Registry itself).

I was expecting to register something in Registry but it wasn't like this.
And with the service manager I had some problems, with the port, because the connection with 8100 port was not done.
I had to modify a file and to add some code for 8100 port.

But I did it and it works now.”
}}

=== Installing with the free MS Visual C++ Toolkit 2003 ===
{{Documentation/HelpNeeded|This section needs help for update because '''MS Visual C++ Toolkit 2003''' seems no more available. Please have a look at Microsoft for the free Visual C++ tools at the moment.}}
I have installed DevCpp to have a make executable file.
I have downloaded the free Visual C++ Toolkit 2003 here :
http://www.microsoft.com/downloads/details.aspx?FamilyID=272be09d-40bb-49fd-9cb0-4bfa122fa91b&displaylang=en

and then I have installed it. '''(This link is broken.)'''

I launch first C:\openoffice\OpenOffice.org2.0_SDK\configureWindowsNT.bat
which asks any questions :
<pre>
set OO_SDK_HOME=C:\openoffice\OpenOffice.org2.0_SDK
set OFFICE_HOME=C:\Program Files\OpenOffice.org 2.0
set OO_SDK_MAKE_HOME=C:\Dev-C++\Bin
set OO_SDK_CPP_HOME=C:\Program Files\Microsoft Visual C++ Toolkit 2003\Bin
set OO_SDK_JAVA_HOME=C:\Program Files\Java\jdk1.5.0_03
</pre>

and I am ready to launch setsdkenv_windows.bat

I have modified the following file :
C:\openoffice\OpenOffice.org2.0_SDK\examples\DevelopersGuide\ProfUNO\CppBinding\office_connect.cxx
to change the port accordingly to what OOo is listening.

I have modified the makefile :
added :
<pre>
CC_INCLUDES = -I"C:\Program Files\Microsoft Visual C++ Toolkit 2003\include" \
-I"C:\openoffice\OpenOffice.org2.0_SDK\include"
</pre>

and added libraries too :

<pre>
$(OUT_BIN)/%$(EXE_EXT) : $(SAMPLE_OBJ_OUT)/%.$(OBJ_EXT)
-$(MKDIR) $(subst /,$(PS),$(@D))
-$(MKDIR) $(subst /,$(PS),$(SAMPLE_GEN_OUT))
ifeq "$(OS)" "WIN"
$(LINK) $(EXE_LINK_FLAGS) /OUT:$@ /MAP:$(SAMPLE_GEN_OUT)/$(subst $(EXE_EXT),.map,$(@F)) \
$< $(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB)\
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libcp.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libc.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\oldnames.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\kernel32.lib"
else
$(LINK) $(EXE_LINK_FLAGS) $(LINK_LIBS) -o $@ $< \
$(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB) $(STDC++LIB)
endif
</pre>
I suppose there is a more straightforward way to add these libraries with adding the corresponding include path but I am unable to do that with VC++.

I find a solution of the previous problem three weeks later. My problem comes in fact from a bug in setsdkenv_windows.bat. A little correction in the file setsdkenv_windows.bat makes it possible to avoid the makefile modifications :
Put :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "C:\Program Files\Microsoft Visual C++ Toolkit 2003\VCVARS32.bat"
</pre>

instead of :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "%OO_SDK_CPP_HOME%\VCVARS32.bat"
</pre>
I think
<pre>
%OO_SDK_CPP_HOME%\..\VCVARS32.bat
</pre>
could work too (but not checked). You can also move vcvars32.bat in %OO_SDK_CPP_HOME%
("C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin" for me).

=== Other Windows Installations descriptions ===

You can find in [http://www.oooforum.org/forum/viewtopic.phtml?t=23772 OOoForum] a post entitled Guide for develop OpenOffice apps with VC++ .net (by [[CppSDKAuthors|LarsB]])

1.Download and install OpenOffice.

2.Download and install OpenOffice SDK

3.Create a new folder inludecpp in <oo_sdk_path>

4.Open Dos console change directory to <oo_sdk_path>\windows\bin

4.1 run cppumaker with followig paramerers
<pre>
cppumaker -BUCR -O <oo_sdk_path>\includecpp <office_programm_dir>\types.rdb
</pre>
or better with
<pre>
cppumaker -Gc -BUCR -O<includes_path> <ooffice_path>\URE\misc\types.rdb <ooffice_path>\Basis\program\offapi.rdb
</pre>
in recent versions.

(Attention: If you recieve a init error, copy types.rdb into the <oo_sdk_path>\windows\bin folder!)
After that all hpp and hdl files should be created in <oo_sdk_path>\includecpp

5.Open Visual Studio and create a new Win32 Console Application.
Applay the following changes to your project.

5.1. Tools ->Options->Projects->VC++ Directories -> Include Files
Add \include directory and <oo_sdk_path>\includecpp

5.2. Tools ->Options->Projects->VC++ Directories -> Library files
Add <oo_sdk_path>\windows\lib directory

5.3. Tools ->Options->Projects->VC++ Directories -> Executable files
Add <office_programm_dir>\program directory (location where you installed the version of the OpenOffice)

5.4 Open the Project Settings

5.4.1 Change Configuration to all All Configurations (the combobox in the left corner of the window)

5.4.2 Add the additional libraries

Properties->Linker->ComandLine in the Additional Options tab the library files
isal.lib icppu.lib icppuhelper.lib isal.lib isalhelper.lib ireg.lib irmcxt.lib stlport_vc71.lib

6.(example) Add the DocumentLoader.cxx from the cpp examples of the sdk
and compile. The source should compile without errors.

INFO : If you got the following error have a look at the solution 2 postings above!
Up to now, with the steps above i got the following error, when i run the DocumentLoader example.
The error is thrown, when the prog execution reach the following line:

<pre>

Reference< XSimpleRegistry > xSimpleRegistry( ::cppu::createSimpleRegistry() );
</pre>

with error shown below :

<pre>
Error:
Window title: Microsoft Visual C++ Debug Library
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

If somebody has experience with this kind of error it will be nice if he could
post a solution. So that here is a complete little guide for OpenOffice with VC++ .NET

Regards
[[CppSDKAuthors|Lars]]

[[CppSDKAuthors|François]] has improved the complete procedure with remarks :
Following all the steps I (_francois_) encountered two problems

* first in point 4.4.2

But there I guess it's because the procedure was meant for SDK 2 and I'm using SDK 1.1
The stlport_vc71.lib which you must include is distributed with the SDK 2 in the SDK 1.1 stlport_vc7.lib
you just need to include the stlport_vc7.lib instead of stlport_vc71.lib

* second problem after successfuly compiling the DocumentLoader in Visual Studio I was getting the following error
Error:
<pre>
Window title: Microsoft Visual C++ Debug Libary
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

After going on debug in the visual studio I found the following line was responsible

<pre>
xSimpleRegistry->open( OUString( RTL_CONSTASCII_USTRINGPARAM("DocumentLoader.rdb") ), sal_True, sal_False );
</pre>

The DocumentLoader.rdb was missing ... I noticed that if I compiled the DocumentLoader exemples from command line with the makefile provided with the exemple a DocumentLoader.rdb was generated. I had a look at the Makefile I isolated the lines which seemed to generate the DocumentLoader.rdb into my Debug folder (or wherever your set your DocumentLoader.exe to be put by Visual Studio) in my Visual Studio project...

<pre>
regmerge c:\travail\DocumentLoader\debug\DocumentLoader.rdb / "C:\ooo\office\program\types.rdb"

regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c connector.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c remotebridge.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c bridgefac.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c uuresolver.uno.dll
</pre>

I launched all the above lines in the prompt shell and it worked I had my DocumentLoader.rdb in my Debug folder

I launched my exe file and it worked, great...

Now I guess I still need to figure out which *.uno.dll needs to be included for which functions used in the programm, but still it's a good start.
If anyone has any information about that (It may actualy be documented somewhere) don't hesitate)

== The Development Tools of the SDK ==

There are several development tools provided with the SDK : idlc, cppumaker, javamaker, rdbmaker, pkgchk, regcomp, regmerge, regview, xml2cmp, uno, and autodoc. You can find a short documentation on these tools at <OOo_SDK>/docs/tools.html and also in [[Documentation/DevGuide/WritingUNO/Required_Files|Developer's Guide]].

See also [[Compiler_versions_used_by_port_maintainers_and_release_engineers|Compiler versions used by port maintainers and release engineers]]

{{Template:Home_Page}}

= See also =
* [[FR/Documentation/Installation_du_SDK|French version of this chapter]].
* [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno|C++ and UNO tutorial]]
* [http://www.codeproject.com/KB/wtl/Wtl_OOo.aspx Prepare the OOo SDK]
* [http://www.oooforum.org/forum/viewtopic.phtml?t=79911&highlight= missing files in sdk]
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal

[[Category:Tutorial]]
[[Category:Cpp]]
[[Category:Uno]]

OpenOffice NetBeans Integration

2014-07-08T20:07:50Z

Global667: /* From source */ make some clearer

[[image:OOo-Netbeans-Plugin.png|right]]
= Overview =
The OpenOffice.org API plugin for NetBeans simplifies the development of OpenOffice.org extensions. You can use the OpenOffice.org API to program OpenOffice.org, and automate remote or in process tasks extend OpenOffice.org with completely new functionality. The OpenOffice.org API plugin for NetBeans simplifies accessing and using of the API in new projects and simplifies the task of creating complete OpenOffice.org extension packages (comparable to the NetBeans plugin modules).

= Download and Installation =
The plugin appears automatically in Netbeans 6.5.x, 6.7.x, 6.8 (version 2.0.6) but is not listed for later versions.

The plugin is available for download from [http://people.apache.org/~cmarcum/devtools/ http://people.apache.org/~cmarcum/devtools/] provided by Carl Marcum. Use 3.x versions for extension development for OpenOffice.org versions 3.0 thru 3.4. Use the latest 4.0.5 alpha version for extension development for Apache OpenOffice 4.x. This version is under active development and will be made available in the NetBeans plugin manager list when finished. Until then, remember that it is an '''Beta''' version.

The configuration is self explanatory, for detailed information see [[OpenOffice_NetBeans_Integration#Configuration|Configuration]].

The source is available in the Apache OpenOffice.org source SVN repository in the '''devtools''' tree. The trunk is under development and the tagged 3.0.0.beta will build and run.
<blockquote>[https://svn.apache.org/repos/asf/openoffice/devtools/netbeansintegration/trunk https://svn.apache.org/repos/asf/openoffice/devtools/netbeansintegration/trunk]</blockquote>

== From source ==
The NetBeans-plugin for 4.1.0 is beta and you need to compile by hand. It doesn't support C++ development for now.
* Install NetBeans from https://netbeans.org/downloads/ take "Java SE" or "All" Package
* Under NetBeans create a new SVN (anonymous) repository to https://svn.apache.org/repos/asf/openoffice/devtools/netbeansintegration/ and checkout
* Create a NBM from the project you get from SVN. On errors install the needed plugins like junit.
* Install the NBM, now you find the OpenOffice Project under "New Project..."

= Features =
Overview of the features included in the current plugin.
== Project Types ==
Click on "File" - "New Project..." and choose category "OpenOffice.org" to open a new project. All project types create working code. Once the project wizard is finished, a working
compilable project is created. It may not do anything, but it can be used
in OpenOffice.org from the beginning.

*'''[[OpenOffice_Simple_UNO_Client_Application_Project_Type|OpenOffice.org Client Application Project Type]]'''
This project type creates an adapted J2SE client application project with additional support of the
simple UNO bootstrap feature. To enable this, some pre-compiled glue code is bundled with the client
application. The result is a portable jar file that bootstraps OpenOffice.org on any supported OS.

*'''[[OpenOffice_Calc_Add-In_Project_Type|OpenOffice.org Calc Add-In Project Type]]'''
This project type creates an adapted J2SE class library project with special support for a UNO
component library and an office extension package. The wizard collects the necessary information for new
Calc built-in functions and abstracts from the underlying UNO technology.

*'''[[General_UNO_Component_Project_Type|General UNO Component Project Type]]'''
This project type creates an adapted J2SE class library project with special support for a
UNO component library and an OpenOffice.org extension package. The wizard collects information about services
and additional optional interfaces which should be implemented. Additional IDL types can also be
defined. A complete code skeleton is generated, with the component helper functions and the default interface methods already implemented.

*'''[[OpenOffice_Add-On_Project_Type|OpenOffice.org Add-On Project Type]]'''
This project type creates an adapted J2SE class library project with special support for a UNO
component library and an OpenOffice.org extension package. The wizard collects the necessary information for an
OpenOffice.org Add-On component and generates an Add-On specific code skeleton.

== File Types ==
Click on "File" - "New File..." and select "OpenOffice.org" as category to create a new file for an OpenOffice.org project. Note, that the OpenOffice.org category is available in all projects, although it only makes sense to use it in one of the projects stated above.
*'''xcu file type'''
Create an empty xcu file type. The files are recognized in NetBeans and
syntax highlighting is supported.

*'''xcs file type'''
Create an empty xcs file type. The files are recognized in NetBeans and
syntax highlighting is supported.

*'''UNO idl file type'''
You can use a file type wizard to create idl files. In the first step, you must select the name location
and UNO type (e.g. Service or Interface). You can add additional
information in the second step. When an interface is created, the second step asks about
the functions that the interface should contain. A complete working idl file is created, and NetBeans provides syntax highlighting. When you choose
to also create an implementation object (only available for service or interface), a Java skeleton file implementing
your new idl file will also be created.

*'''Java UNO Object file type'''
This file wizard creates a Java skeleton file that implements all functions defined in an interface or service idl file. If you choose a service, the Java implementation file will also be
registered in OpenOffice.org when your extension is deployed.

== Create, deploy and debug ==
These are actions that are available in the context menu of an extension project in the "Project"
view.

*'''Debug Extension in Target OpenOffice.org'''
If necessary, "Create OXT" is executed. The resulting OXT file is registered in a temporary user installation of OpenOffice.org, which is located in the build directory of the project. (Cleaning of the project removes the user installation again.) Then OpenOffice.org is started with this user installation. To trigger the registered extension, an appropriate action must be done in OpenOffice.org.
Execution stops at any breakpoints added to the code of the extension and debugging can start from there.

*'''Deploy and Run OpenOffice.org Extension'''
If necessary, "Create OXT" is executed. The resulting OXT file is registered inside the user installation of OpenOffice.org. Then OpenOffice.org is started.

*'''Create OXT'''
If necessary, your code is compiled. The resulting jar file is packed into an OXT file, together with other necessary files such as configuration files, a manifest file, and images. The OXT file is located in the "dist" directory of the project.

*'''Publish Extension on OpenOffice.org Website'''
The starting page for uploading and publishing your extension on api.services.openoffice.org is loaded in your default web browser.

== Miscellaneous ==
*'''External Jars'''
Additional external jars that are used in an extension are automatically copied into the OXT file and added to the extension's classpath. A registered extension in OpenOffice.org can still use the functionality provided there.
The jars can be added to the project as a single jar or as part of a NetBeans library. Note: All the jars from a library will be added to the OXT file, independent from their usage in the extension.

== Specifications ==

Find here links to the specifications of the plugin on the api.openoffice.org page.

[http://specs.openoffice.org/sdk/tools/spec_openoffice-netbeans-integration.odt OpenOffice.org Plugin for NetBeans]

[http://specs.openoffice.org/sdk/tools/spec_openoffice-netbeans-integration-addon-wizard.odt OpenOffice.org Plugin for NetBeans: Add-On Wizard]

[http://specs.openoffice.org/sdk/tools/spec_openoffice-netbeans-integration-calc-addin-wizard.odt OpenOffice.org Plugin for NetBeans: Add-In Wizard]

[http://specs.openoffice.org/sdk/tools/spec_openoffice-netbeans-integration-component-wizard.odt OpenOffice.org Plugin for NetBeans: Component Wizard]

[http://specs.openoffice.org/sdk/tools/spec_openoffice-netbeans-integration-debug-component.odt OpenOffice.org Plugin for NetBeans: Debug Feature]

[http://specs.openoffice.org/sdk/tools/spec_openoffice-netbeans-integration-new-idl-type.odt OpenOffice.org Plugin for NetBeans: IDL type support]

[http://specs.openoffice.org/sdk/tools/spec_openoffice-netbeans-integration-description-xml.odt OpenOffice.org Plugin for NetBeans: Support description.xml]

= Working with the plugin =
The following section describes how you can work with the plugin and describes the requirements because the plugin make use of some external stuff provided by an office and the OpenOffice.org SDK.

== Requirements ==
The plugin works only in combination with OpenOffice.org and an appropriate OpenOffice.org Software Development Kit (SDK). The minimal suggested version is OpenOffice.org 2.0.4. With earlier versions, some features of the plugin will not work.

*'''[http://download.openoffice.org OpenOffice.org]''' or '''[http://www.sun.com/staroffice StarOffice 8]''' or higher versions of both programs
*'''[http://download.openoffice.org/sdk.html OpenOffice.org Software Development Kit (SDK)]'''

Note that the versions of OpenOffice.org and the OpenOffice.org SDK must match for everything to work.

== Configuration ==
Before you can use the new project types you must configure the plugin because it needs an installed OpenOffice.org and OpenOffice.org SDK.

Note:
* As default settings, a standard installation will be found by the plugin - but only if OpenOffice.org together with the SDK are present.
* When you choose the OpenOffice.org installation and an appropriate SDK is found, that SDK is chosen, the "OpenOffice.org SDK Installation" field is then disabled.
* If you change the OpenOffice.org or OpenOffice.org SDK installation, these changes are effective for projects created from now on only.

For changing the office and SDK installation please choose
*'' '''Tools -> Options -> Miscellaneous -> OOo API plugin''' ''
and select a valid OpenOffice.org and OpenOffice.org SDK installation.
 [[Image:OpenOffice_Extensions_Plugin_Options.png|center]] 
The configuration step automatically installs a new OpenOffice.org library which can be used in other projects to support the OpenOffice.org API. Including this library in your own projects enables context sensitive help and code completion.

Note: on Debian/Ubuntu, the OpenOffice.org installation directory is <code>/usr/lib/openoffice/</code>. For other *nix platforms the location may vary, but you can find the location by inspecting the shell script <code>/usr/bin/ooffice</code> to see where the <code>ooqstart</code> executable is in your installation.

== Working with new Project Types ==
The plugin integrates four new project types under the category '''StarOffice/OpenOffice.org''':
*'''StarOffice/OpenOffice.org Add-On'''
*'''StarOffice/OpenOffice.org Calc Add-Ins'''
*'''StarOffice/OpenOffice.org Client Application'''
*'''StarOffice/OpenOffice.org Component'''

The wizards will collect the necessary information to create the new projects and should follow the NetBeans philosophy. You can simply choose
*'' '''File -> New Project -> OpenOffice.org -> <project_type>''' ''
For more details about the project types please take a look at
*[[OpenOffice_Simple_UNO_Client_Application_Project_Type|OpenOffice.org UNO Client Application Project Type]]
*[[OpenOffice_Calc_Add-In_Project_Type|OpenOffice.org Calc Add-In Project Type]]
*[[General_UNO_Component_Project_Type|OpenOffice.org Component Project Type]]
*[[OpenOffice_Add-On_Project_Type|OpenOffice.org Add-On Project Type]]

== Migrate Projects ==
To migrate projects from an older version of the plugin to a new one is not necessary - the plugin itself will take care of that: build-uno-impl.xml and the project-uno.properties are updated, when updated versions of these files are needed for new features of the updated plugin. Note that build-uno-impl.xml will be overwritten, but project-uno.properties not. In the properties file, only new entries are added, existing ones are kept as they are. The update of the files happens when an old project is opened with a new version of the plugin and for all opened projects when the new plugin is downloaded and installed.

When migrating from one Office version to another (or porting a project across platforms), only a library has to be changed, called "OpenOffice.org <version_number>" (or "StarOffice <version_number>"). Choose '''Tools -> Libraries''' to get an overview of the existing libraries. A library is created when a valid OpenOffice.org and OpenOffice.org SDK is selected in '''Tools -> Options -> Miscellaneous -> OOo API Plugin''' (See [[OpenOffice_NetBeans_Integration#Configuration|Configuration]] for more details).
* To change the library, click right on the project in the '''Project''' window and open the properties. Select '''Libraries''' as category and remove the one that points to the old installation and add the new one.
* When porting the project across platforms, NetBeans notifies that a reference problem exists. The steps for changing the libraries also help in this case.

== Known Problems and Missing Features ==

* Context sensitive help does not work on Linux (Solaris not yet tested), even the javadoc generated Java UNO runtime reference documentation does not work on Linux. Under Windows both work as expected.
* "Red Dot Problem": When you have created a project that supports own idl files (e.g. a Clac AddIn), a "clean" on the project will produce "red dots" that show that imported functionality is missing. The cause for this is the deleted jar file with the idl types that are used in your project. Although this does not seem to be the case, a compile will work and solve the problem. Sometimes the signs appear when "clean and build" is chosen - here the compiled idl files exist, but NetBeans does not recognize that. Open the offending Java file to solve that. Solution: compile idl files in the background and produce a "shadow" jar file in a temp directory that can be used even if the "official" file in the <project_name>/dist folder is deleted.
* With NetBeans versions at least 6.1 there is an update problem regarding NetBeans property sheets and node views: property sheet changes are not reflected in the node view. Seems like the notify mechanism for these updates has changed.

= Releases =

{|cellpadding=5 cellspacing=0 border=1 style="border-collapse:collapse; margin-left: 3em; border-color: #333;"
|- style="background-color: #DEDEDE;"
| Release Version || Planned Release Date || Release Date || Planned Features
|- align=center
| 1.0 || 05/08/07 || 05/08/07 || -
|- align=center
| 1.1 || 09/01/07 || 09/18/07 || [[OpenOffice_NetBeans_Integration/Releases/Release_1.1| see 1.1]]
|- align=center
| 1.1.1 || 03/08 || 03/20/08 || [[OpenOffice_NetBeans_Integration/Releases/Release_1.1.x| see 1.1.1]]
|- align=center
| 1.1.2 || 04/08 || 04/30/08 || [[OpenOffice_NetBeans_Integration/Releases/Release_1.1.x| see 1.1.2]]
|- align=center
| 1.1.3 || 06/30/08 || - || [[OpenOffice_NetBeans_Integration/Releases/Release_1.1.x| see 1.1.3]]
|- align=center
| 2.0 || 09/08 || - || [[OpenOffice_NetBeans_Integration/Releases/Release_2.0| see 2.0]]
|- align=center
| 2.0.3 || - || - || bugfixes only
|- align=center
| 2.0.4 || - || - || bugfixes only
|- align=center
| 2.0.5 || - || - || bugfixes only
|- align=center
| 2.0.6 || - || - || bugfixes only
|- align=center
| 2.0.7.alpha || - || - || changes to support NetBeans 6.9, opnly available in the file section of the API project, [http://api.openoffice.org/files/documents/22/4772/org-openoffice-extensions-2.0.7.alpha.nbm org-openoffice-extensions-2.0.7.alpha.nbm]
|}

:   Detailed download statistics can be found [[OpenOffice_NetBeans_Integration/Releases/Download_Statistic| here]] (not up-to-date)

* [[OpenOffice_NetBeans_Integration/Releases/Release_1.2#Current_issues_concerning_NetBeans_6|Issues]] for using the plugin with NetBeans 6.

= Planned Features =
The focus is on creating new wizards for various tasks plus common basic functionality. The main programming language is Java. Support for C++ is also planned and depends on the C++ support in NetBeans which will be available at least for NetBeans 6.0. The planned feature list is not final and more specialized wizards for other service provider interfaces (SPI) are coming in the future.

== New Project Types ==
*'''[[OpenOffice_Scripting_Project_Type|OpenOffice.org Scripting Project Type]]''' This new project type will create an adapted J2SE class library project with special support for OpenOffice.org scripting. It should provide you the possibility to import scripts from OpenOffice.org and open documents, edit, change and build these scripts, debug them and export them back (currently the support is planned for Java scripts only).
*'''[[OpenOffice_SmartTag_Project_Type|OpenOffice.org SmartTag Project Type]]''' This new project type will simplify the development of SmartTags for the OpenOffice.org Writer application.
*'''[[OpenOffice_API_Library_Wrapper_Project_Type|OpenOffice.org API Library API Wrapper Project Type]]''' This new project type should create a ''Library Wrapper Module'' to support simple usage of the OpenOffice.org API in your own projects. It bundles the necessary API jar files from OpenOffice.org in the library and in client applications. This of course is necessary to make use of the OpenOffice.org API in clients running on machines where no OpenOffice.org is installed and where the communication with OpenOffice.org is made over a remote socket connection.

== Common Features ==
*'''Editor for xcu files''' This must be defined in detail but we can think of a special editor for OpenOffice .org configuration files.

= Quality Assurance =

If you find bugs please submit a new [http://api.openoffice.org/issues/enter_bug.cgi?component=sdk&issue_type=DEFECT issue] in the category '''sdk''' and the subcomponent '''netbeans-integration'''

* [[OpenOffice_NetBeans_Integration_QA|Schedule for OpenOffice.org NetBeans Integration QA ]]

= Localization =
* [[OpenOffice_NetBeans_Integration/Localization|Localization Tutorial]]

= Things to be done =
* [[OpenOffice_NetBeans_Integration/To-Dos|ToDo list]]

= Feedback =
We will continuously extend and improve the plugin in the future and your feedback is welcome and highly appreciated. We would like to invite you to discuss it on [mailto:dev@api.openoffice.org dev@api.openoffice.org] (Note: you have to be subscribed on the mailing list).

You can also submit new [http://api.openoffice.org/issues/enter_bug.cgi?component=sdk&issue_type=FEATURE feature] or [http://api.openoffice.org/issues/enter_bug.cgi?component=sdk&issue_type=ENHANCEMENT enhancement] requests in the issue tracker in the category '''sdk''' and the subcomponent '''netbeans-integration'''

[[Category:NetBeans]]
[[Category:API]]
[[Category:Effort]]

OpenOffice NetBeans Integration

2014-07-08T13:05:23Z

Global667: /* Build and install from source */ Clearer headline

[[image:OOo-Netbeans-Plugin.png|right]]
= Overview =
The OpenOffice.org API plugin for NetBeans simplifies the development of OpenOffice.org extensions. You can use the OpenOffice.org API to program OpenOffice.org, and automate remote or in process tasks extend OpenOffice.org with completely new functionality. The OpenOffice.org API plugin for NetBeans simplifies accessing and using of the API in new projects and simplifies the task of creating complete OpenOffice.org extension packages (comparable to the NetBeans plugin modules).

= Download and Installation =
The plugin appears automatically in Netbeans 6.5.x, 6.7.x, 6.8 (version 2.0.6) but is not listed for later versions.

The plugin is available for download from [http://people.apache.org/~cmarcum/devtools/ http://people.apache.org/~cmarcum/devtools/] provided by Carl Marcum. Use 3.x versions for extension development for OpenOffice.org versions 3.0 thru 3.4. Use the latest 4.0.5 alpha version for extension development for Apache OpenOffice 4.x. This version is under active development and will be made available in the NetBeans plugin manager list when finished. Until then, remember that it is an '''Beta''' version.

The configuration is self explanatory, for detailed information see [[OpenOffice_NetBeans_Integration#Configuration|Configuration]].

The source is available in the Apache OpenOffice.org source SVN repository in the '''devtools''' tree. The trunk is under development and the tagged 3.0.0.beta will build and run.
<blockquote>[https://svn.apache.org/repos/asf/openoffice/devtools/netbeansintegration/trunk https://svn.apache.org/repos/asf/openoffice/devtools/netbeansintegration/trunk]</blockquote>

== From source ==
The NetBeans-plugin for 4.1.0 is beta and you need to compile by hand. It seems that it doesn't support C++ development for now.
* Install NetBeans from https://netbeans.org/downloads/ take "Java SE" or "All" Package
* Under NetBeans create a new SVN (anonymous) repository to https://svn.apache.org/repos/asf/openoffice/devtools/netbeansintegration/ and checkout
* Create a NBM from the project you get from SVN. On errors install the needed plugins like junit.
* Install the NBM

= Features =
Overview of the features included in the current plugin.
== Project Types ==
Click on "File" - "New Project..." and choose category "OpenOffice.org" to open a new project. All project types create working code. Once the project wizard is finished, a working
compilable project is created. It may not do anything, but it can be used
in OpenOffice.org from the beginning.

*'''[[OpenOffice_Simple_UNO_Client_Application_Project_Type|OpenOffice.org Client Application Project Type]]'''
This project type creates an adapted J2SE client application project with additional support of the
simple UNO bootstrap feature. To enable this, some pre-compiled glue code is bundled with the client
application. The result is a portable jar file that bootstraps OpenOffice.org on any supported OS.

*'''[[OpenOffice_Calc_Add-In_Project_Type|OpenOffice.org Calc Add-In Project Type]]'''
This project type creates an adapted J2SE class library project with special support for a UNO
component library and an office extension package. The wizard collects the necessary information for new
Calc built-in functions and abstracts from the underlying UNO technology.

*'''[[General_UNO_Component_Project_Type|General UNO Component Project Type]]'''
This project type creates an adapted J2SE class library project with special support for a
UNO component library and an OpenOffice.org extension package. The wizard collects information about services
and additional optional interfaces which should be implemented. Additional IDL types can also be
defined. A complete code skeleton is generated, with the component helper functions and the default interface methods already implemented.

*'''[[OpenOffice_Add-On_Project_Type|OpenOffice.org Add-On Project Type]]'''
This project type creates an adapted J2SE class library project with special support for a UNO
component library and an OpenOffice.org extension package. The wizard collects the necessary information for an
OpenOffice.org Add-On component and generates an Add-On specific code skeleton.

== File Types ==
Click on "File" - "New File..." and select "OpenOffice.org" as category to create a new file for an OpenOffice.org project. Note, that the OpenOffice.org category is available in all projects, although it only makes sense to use it in one of the projects stated above.
*'''xcu file type'''
Create an empty xcu file type. The files are recognized in NetBeans and
syntax highlighting is supported.

*'''xcs file type'''
Create an empty xcs file type. The files are recognized in NetBeans and
syntax highlighting is supported.

*'''UNO idl file type'''
You can use a file type wizard to create idl files. In the first step, you must select the name location
and UNO type (e.g. Service or Interface). You can add additional
information in the second step. When an interface is created, the second step asks about
the functions that the interface should contain. A complete working idl file is created, and NetBeans provides syntax highlighting. When you choose
to also create an implementation object (only available for service or interface), a Java skeleton file implementing
your new idl file will also be created.

*'''Java UNO Object file type'''
This file wizard creates a Java skeleton file that implements all functions defined in an interface or service idl file. If you choose a service, the Java implementation file will also be
registered in OpenOffice.org when your extension is deployed.

== Create, deploy and debug ==
These are actions that are available in the context menu of an extension project in the "Project"
view.

*'''Debug Extension in Target OpenOffice.org'''
If necessary, "Create OXT" is executed. The resulting OXT file is registered in a temporary user installation of OpenOffice.org, which is located in the build directory of the project. (Cleaning of the project removes the user installation again.) Then OpenOffice.org is started with this user installation. To trigger the registered extension, an appropriate action must be done in OpenOffice.org.
Execution stops at any breakpoints added to the code of the extension and debugging can start from there.

*'''Deploy and Run OpenOffice.org Extension'''
If necessary, "Create OXT" is executed. The resulting OXT file is registered inside the user installation of OpenOffice.org. Then OpenOffice.org is started.

*'''Create OXT'''
If necessary, your code is compiled. The resulting jar file is packed into an OXT file, together with other necessary files such as configuration files, a manifest file, and images. The OXT file is located in the "dist" directory of the project.

*'''Publish Extension on OpenOffice.org Website'''
The starting page for uploading and publishing your extension on api.services.openoffice.org is loaded in your default web browser.

== Miscellaneous ==
*'''External Jars'''
Additional external jars that are used in an extension are automatically copied into the OXT file and added to the extension's classpath. A registered extension in OpenOffice.org can still use the functionality provided there.
The jars can be added to the project as a single jar or as part of a NetBeans library. Note: All the jars from a library will be added to the OXT file, independent from their usage in the extension.

== Specifications ==

Find here links to the specifications of the plugin on the api.openoffice.org page.

[http://specs.openoffice.org/sdk/tools/spec_openoffice-netbeans-integration.odt OpenOffice.org Plugin for NetBeans]

[http://specs.openoffice.org/sdk/tools/spec_openoffice-netbeans-integration-addon-wizard.odt OpenOffice.org Plugin for NetBeans: Add-On Wizard]

[http://specs.openoffice.org/sdk/tools/spec_openoffice-netbeans-integration-calc-addin-wizard.odt OpenOffice.org Plugin for NetBeans: Add-In Wizard]

[http://specs.openoffice.org/sdk/tools/spec_openoffice-netbeans-integration-component-wizard.odt OpenOffice.org Plugin for NetBeans: Component Wizard]

[http://specs.openoffice.org/sdk/tools/spec_openoffice-netbeans-integration-debug-component.odt OpenOffice.org Plugin for NetBeans: Debug Feature]

[http://specs.openoffice.org/sdk/tools/spec_openoffice-netbeans-integration-new-idl-type.odt OpenOffice.org Plugin for NetBeans: IDL type support]

[http://specs.openoffice.org/sdk/tools/spec_openoffice-netbeans-integration-description-xml.odt OpenOffice.org Plugin for NetBeans: Support description.xml]

= Working with the plugin =
The following section describes how you can work with the plugin and describes the requirements because the plugin make use of some external stuff provided by an office and the OpenOffice.org SDK.

== Requirements ==
The plugin works only in combination with OpenOffice.org and an appropriate OpenOffice.org Software Development Kit (SDK). The minimal suggested version is OpenOffice.org 2.0.4. With earlier versions, some features of the plugin will not work.

*'''[http://download.openoffice.org OpenOffice.org]''' or '''[http://www.sun.com/staroffice StarOffice 8]''' or higher versions of both programs
*'''[http://download.openoffice.org/sdk.html OpenOffice.org Software Development Kit (SDK)]'''

Note that the versions of OpenOffice.org and the OpenOffice.org SDK must match for everything to work.

== Configuration ==
Before you can use the new project types you must configure the plugin because it needs an installed OpenOffice.org and OpenOffice.org SDK.

Note:
* As default settings, a standard installation will be found by the plugin - but only if OpenOffice.org together with the SDK are present.
* When you choose the OpenOffice.org installation and an appropriate SDK is found, that SDK is chosen, the "OpenOffice.org SDK Installation" field is then disabled.
* If you change the OpenOffice.org or OpenOffice.org SDK installation, these changes are effective for projects created from now on only.

For changing the office and SDK installation please choose
*'' '''Tools -> Options -> Miscellaneous -> OOo API plugin''' ''
and select a valid OpenOffice.org and OpenOffice.org SDK installation.
 [[Image:OpenOffice_Extensions_Plugin_Options.png|center]] 
The configuration step automatically installs a new OpenOffice.org library which can be used in other projects to support the OpenOffice.org API. Including this library in your own projects enables context sensitive help and code completion.

Note: on Debian/Ubuntu, the OpenOffice.org installation directory is <code>/usr/lib/openoffice/</code>. For other *nix platforms the location may vary, but you can find the location by inspecting the shell script <code>/usr/bin/ooffice</code> to see where the <code>ooqstart</code> executable is in your installation.

== Working with new Project Types ==
The plugin integrates four new project types under the category '''StarOffice/OpenOffice.org''':
*'''StarOffice/OpenOffice.org Add-On'''
*'''StarOffice/OpenOffice.org Calc Add-Ins'''
*'''StarOffice/OpenOffice.org Client Application'''
*'''StarOffice/OpenOffice.org Component'''

The wizards will collect the necessary information to create the new projects and should follow the NetBeans philosophy. You can simply choose
*'' '''File -> New Project -> OpenOffice.org -> <project_type>''' ''
For more details about the project types please take a look at
*[[OpenOffice_Simple_UNO_Client_Application_Project_Type|OpenOffice.org UNO Client Application Project Type]]
*[[OpenOffice_Calc_Add-In_Project_Type|OpenOffice.org Calc Add-In Project Type]]
*[[General_UNO_Component_Project_Type|OpenOffice.org Component Project Type]]
*[[OpenOffice_Add-On_Project_Type|OpenOffice.org Add-On Project Type]]

== Migrate Projects ==
To migrate projects from an older version of the plugin to a new one is not necessary - the plugin itself will take care of that: build-uno-impl.xml and the project-uno.properties are updated, when updated versions of these files are needed for new features of the updated plugin. Note that build-uno-impl.xml will be overwritten, but project-uno.properties not. In the properties file, only new entries are added, existing ones are kept as they are. The update of the files happens when an old project is opened with a new version of the plugin and for all opened projects when the new plugin is downloaded and installed.

When migrating from one Office version to another (or porting a project across platforms), only a library has to be changed, called "OpenOffice.org <version_number>" (or "StarOffice <version_number>"). Choose '''Tools -> Libraries''' to get an overview of the existing libraries. A library is created when a valid OpenOffice.org and OpenOffice.org SDK is selected in '''Tools -> Options -> Miscellaneous -> OOo API Plugin''' (See [[OpenOffice_NetBeans_Integration#Configuration|Configuration]] for more details).
* To change the library, click right on the project in the '''Project''' window and open the properties. Select '''Libraries''' as category and remove the one that points to the old installation and add the new one.
* When porting the project across platforms, NetBeans notifies that a reference problem exists. The steps for changing the libraries also help in this case.

== Known Problems and Missing Features ==

* Context sensitive help does not work on Linux (Solaris not yet tested), even the javadoc generated Java UNO runtime reference documentation does not work on Linux. Under Windows both work as expected.
* "Red Dot Problem": When you have created a project that supports own idl files (e.g. a Clac AddIn), a "clean" on the project will produce "red dots" that show that imported functionality is missing. The cause for this is the deleted jar file with the idl types that are used in your project. Although this does not seem to be the case, a compile will work and solve the problem. Sometimes the signs appear when "clean and build" is chosen - here the compiled idl files exist, but NetBeans does not recognize that. Open the offending Java file to solve that. Solution: compile idl files in the background and produce a "shadow" jar file in a temp directory that can be used even if the "official" file in the <project_name>/dist folder is deleted.
* With NetBeans versions at least 6.1 there is an update problem regarding NetBeans property sheets and node views: property sheet changes are not reflected in the node view. Seems like the notify mechanism for these updates has changed.

= Releases =

{|cellpadding=5 cellspacing=0 border=1 style="border-collapse:collapse; margin-left: 3em; border-color: #333;"
|- style="background-color: #DEDEDE;"
| Release Version || Planned Release Date || Release Date || Planned Features
|- align=center
| 1.0 || 05/08/07 || 05/08/07 || -
|- align=center
| 1.1 || 09/01/07 || 09/18/07 || [[OpenOffice_NetBeans_Integration/Releases/Release_1.1| see 1.1]]
|- align=center
| 1.1.1 || 03/08 || 03/20/08 || [[OpenOffice_NetBeans_Integration/Releases/Release_1.1.x| see 1.1.1]]
|- align=center
| 1.1.2 || 04/08 || 04/30/08 || [[OpenOffice_NetBeans_Integration/Releases/Release_1.1.x| see 1.1.2]]
|- align=center
| 1.1.3 || 06/30/08 || - || [[OpenOffice_NetBeans_Integration/Releases/Release_1.1.x| see 1.1.3]]
|- align=center
| 2.0 || 09/08 || - || [[OpenOffice_NetBeans_Integration/Releases/Release_2.0| see 2.0]]
|- align=center
| 2.0.3 || - || - || bugfixes only
|- align=center
| 2.0.4 || - || - || bugfixes only
|- align=center
| 2.0.5 || - || - || bugfixes only
|- align=center
| 2.0.6 || - || - || bugfixes only
|- align=center
| 2.0.7.alpha || - || - || changes to support NetBeans 6.9, opnly available in the file section of the API project, [http://api.openoffice.org/files/documents/22/4772/org-openoffice-extensions-2.0.7.alpha.nbm org-openoffice-extensions-2.0.7.alpha.nbm]
|}

:   Detailed download statistics can be found [[OpenOffice_NetBeans_Integration/Releases/Download_Statistic| here]] (not up-to-date)

* [[OpenOffice_NetBeans_Integration/Releases/Release_1.2#Current_issues_concerning_NetBeans_6|Issues]] for using the plugin with NetBeans 6.

= Planned Features =
The focus is on creating new wizards for various tasks plus common basic functionality. The main programming language is Java. Support for C++ is also planned and depends on the C++ support in NetBeans which will be available at least for NetBeans 6.0. The planned feature list is not final and more specialized wizards for other service provider interfaces (SPI) are coming in the future.

== New Project Types ==
*'''[[OpenOffice_Scripting_Project_Type|OpenOffice.org Scripting Project Type]]''' This new project type will create an adapted J2SE class library project with special support for OpenOffice.org scripting. It should provide you the possibility to import scripts from OpenOffice.org and open documents, edit, change and build these scripts, debug them and export them back (currently the support is planned for Java scripts only).
*'''[[OpenOffice_SmartTag_Project_Type|OpenOffice.org SmartTag Project Type]]''' This new project type will simplify the development of SmartTags for the OpenOffice.org Writer application.
*'''[[OpenOffice_API_Library_Wrapper_Project_Type|OpenOffice.org API Library API Wrapper Project Type]]''' This new project type should create a ''Library Wrapper Module'' to support simple usage of the OpenOffice.org API in your own projects. It bundles the necessary API jar files from OpenOffice.org in the library and in client applications. This of course is necessary to make use of the OpenOffice.org API in clients running on machines where no OpenOffice.org is installed and where the communication with OpenOffice.org is made over a remote socket connection.

== Common Features ==
*'''Editor for xcu files''' This must be defined in detail but we can think of a special editor for OpenOffice .org configuration files.

= Quality Assurance =

If you find bugs please submit a new [http://api.openoffice.org/issues/enter_bug.cgi?component=sdk&issue_type=DEFECT issue] in the category '''sdk''' and the subcomponent '''netbeans-integration'''

* [[OpenOffice_NetBeans_Integration_QA|Schedule for OpenOffice.org NetBeans Integration QA ]]

= Localization =
* [[OpenOffice_NetBeans_Integration/Localization|Localization Tutorial]]

= Things to be done =
* [[OpenOffice_NetBeans_Integration/To-Dos|ToDo list]]

= Feedback =
We will continuously extend and improve the plugin in the future and your feedback is welcome and highly appreciated. We would like to invite you to discuss it on [mailto:dev@api.openoffice.org dev@api.openoffice.org] (Note: you have to be subscribed on the mailing list).

You can also submit new [http://api.openoffice.org/issues/enter_bug.cgi?component=sdk&issue_type=FEATURE feature] or [http://api.openoffice.org/issues/enter_bug.cgi?component=sdk&issue_type=ENHANCEMENT enhancement] requests in the issue tracker in the category '''sdk''' and the subcomponent '''netbeans-integration'''

[[Category:NetBeans]]
[[Category:API]]
[[Category:Effort]]

OpenOffice NetBeans Integration

2014-07-08T12:34:01Z

Global667: /* Build and install from source */ formatting

[[image:OOo-Netbeans-Plugin.png|right]]
= Overview =
The OpenOffice.org API plugin for NetBeans simplifies the development of OpenOffice.org extensions. You can use the OpenOffice.org API to program OpenOffice.org, and automate remote or in process tasks extend OpenOffice.org with completely new functionality. The OpenOffice.org API plugin for NetBeans simplifies accessing and using of the API in new projects and simplifies the task of creating complete OpenOffice.org extension packages (comparable to the NetBeans plugin modules).

= Download and Installation =
The plugin appears automatically in Netbeans 6.5.x, 6.7.x, 6.8 (version 2.0.6) but is not listed for later versions.

The plugin is available for download from [http://people.apache.org/~cmarcum/devtools/ http://people.apache.org/~cmarcum/devtools/] provided by Carl Marcum. Use 3.x versions for extension development for OpenOffice.org versions 3.0 thru 3.4. Use the latest 4.0.5 alpha version for extension development for Apache OpenOffice 4.x. This version is under active development and will be made available in the NetBeans plugin manager list when finished. Until then, remember that it is an '''Beta''' version.

The configuration is self explanatory, for detailed information see [[OpenOffice_NetBeans_Integration#Configuration|Configuration]].

The source is available in the Apache OpenOffice.org source SVN repository in the '''devtools''' tree. The trunk is under development and the tagged 3.0.0.beta will build and run.
<blockquote>[https://svn.apache.org/repos/asf/openoffice/devtools/netbeansintegration/trunk https://svn.apache.org/repos/asf/openoffice/devtools/netbeansintegration/trunk]</blockquote>

== Build and install from source ==
The NetBeans-plugin for 4.1.0 is beta and you need to compile by hand. It seems that it doesn't support C++ development for now.
* Install NetBeans 8.0 from https://netbeans.org/downloads/ take "Java SE" or "All" Package
* Under NetBeans create a new SVN (anonymous) repository to https://svn.apache.org/repos/asf/openoffice/devtools/netbeansintegration/
* Create a NBM from the project you get from SVN. On errors install the needed plugins like junit.
* Install the NBM

= Features =
Overview of the features included in the current plugin.
== Project Types ==
Click on "File" - "New Project..." and choose category "OpenOffice.org" to open a new project. All project types create working code. Once the project wizard is finished, a working
compilable project is created. It may not do anything, but it can be used
in OpenOffice.org from the beginning.

*'''[[OpenOffice_Simple_UNO_Client_Application_Project_Type|OpenOffice.org Client Application Project Type]]'''
This project type creates an adapted J2SE client application project with additional support of the
simple UNO bootstrap feature. To enable this, some pre-compiled glue code is bundled with the client
application. The result is a portable jar file that bootstraps OpenOffice.org on any supported OS.

*'''[[OpenOffice_Calc_Add-In_Project_Type|OpenOffice.org Calc Add-In Project Type]]'''
This project type creates an adapted J2SE class library project with special support for a UNO
component library and an office extension package. The wizard collects the necessary information for new
Calc built-in functions and abstracts from the underlying UNO technology.

*'''[[General_UNO_Component_Project_Type|General UNO Component Project Type]]'''
This project type creates an adapted J2SE class library project with special support for a
UNO component library and an OpenOffice.org extension package. The wizard collects information about services
and additional optional interfaces which should be implemented. Additional IDL types can also be
defined. A complete code skeleton is generated, with the component helper functions and the default interface methods already implemented.

*'''[[OpenOffice_Add-On_Project_Type|OpenOffice.org Add-On Project Type]]'''
This project type creates an adapted J2SE class library project with special support for a UNO
component library and an OpenOffice.org extension package. The wizard collects the necessary information for an
OpenOffice.org Add-On component and generates an Add-On specific code skeleton.

== File Types ==
Click on "File" - "New File..." and select "OpenOffice.org" as category to create a new file for an OpenOffice.org project. Note, that the OpenOffice.org category is available in all projects, although it only makes sense to use it in one of the projects stated above.
*'''xcu file type'''
Create an empty xcu file type. The files are recognized in NetBeans and
syntax highlighting is supported.

*'''xcs file type'''
Create an empty xcs file type. The files are recognized in NetBeans and
syntax highlighting is supported.

*'''UNO idl file type'''
You can use a file type wizard to create idl files. In the first step, you must select the name location
and UNO type (e.g. Service or Interface). You can add additional
information in the second step. When an interface is created, the second step asks about
the functions that the interface should contain. A complete working idl file is created, and NetBeans provides syntax highlighting. When you choose
to also create an implementation object (only available for service or interface), a Java skeleton file implementing
your new idl file will also be created.

*'''Java UNO Object file type'''
This file wizard creates a Java skeleton file that implements all functions defined in an interface or service idl file. If you choose a service, the Java implementation file will also be
registered in OpenOffice.org when your extension is deployed.

== Create, deploy and debug ==
These are actions that are available in the context menu of an extension project in the "Project"
view.

*'''Debug Extension in Target OpenOffice.org'''
If necessary, "Create OXT" is executed. The resulting OXT file is registered in a temporary user installation of OpenOffice.org, which is located in the build directory of the project. (Cleaning of the project removes the user installation again.) Then OpenOffice.org is started with this user installation. To trigger the registered extension, an appropriate action must be done in OpenOffice.org.
Execution stops at any breakpoints added to the code of the extension and debugging can start from there.

*'''Deploy and Run OpenOffice.org Extension'''
If necessary, "Create OXT" is executed. The resulting OXT file is registered inside the user installation of OpenOffice.org. Then OpenOffice.org is started.

*'''Create OXT'''
If necessary, your code is compiled. The resulting jar file is packed into an OXT file, together with other necessary files such as configuration files, a manifest file, and images. The OXT file is located in the "dist" directory of the project.

*'''Publish Extension on OpenOffice.org Website'''
The starting page for uploading and publishing your extension on api.services.openoffice.org is loaded in your default web browser.

== Miscellaneous ==
*'''External Jars'''
Additional external jars that are used in an extension are automatically copied into the OXT file and added to the extension's classpath. A registered extension in OpenOffice.org can still use the functionality provided there.
The jars can be added to the project as a single jar or as part of a NetBeans library. Note: All the jars from a library will be added to the OXT file, independent from their usage in the extension.

== Specifications ==

Find here links to the specifications of the plugin on the api.openoffice.org page.

[http://specs.openoffice.org/sdk/tools/spec_openoffice-netbeans-integration.odt OpenOffice.org Plugin for NetBeans]

[http://specs.openoffice.org/sdk/tools/spec_openoffice-netbeans-integration-addon-wizard.odt OpenOffice.org Plugin for NetBeans: Add-On Wizard]

[http://specs.openoffice.org/sdk/tools/spec_openoffice-netbeans-integration-calc-addin-wizard.odt OpenOffice.org Plugin for NetBeans: Add-In Wizard]

[http://specs.openoffice.org/sdk/tools/spec_openoffice-netbeans-integration-component-wizard.odt OpenOffice.org Plugin for NetBeans: Component Wizard]

[http://specs.openoffice.org/sdk/tools/spec_openoffice-netbeans-integration-debug-component.odt OpenOffice.org Plugin for NetBeans: Debug Feature]

[http://specs.openoffice.org/sdk/tools/spec_openoffice-netbeans-integration-new-idl-type.odt OpenOffice.org Plugin for NetBeans: IDL type support]

[http://specs.openoffice.org/sdk/tools/spec_openoffice-netbeans-integration-description-xml.odt OpenOffice.org Plugin for NetBeans: Support description.xml]

= Working with the plugin =
The following section describes how you can work with the plugin and describes the requirements because the plugin make use of some external stuff provided by an office and the OpenOffice.org SDK.

== Requirements ==
The plugin works only in combination with OpenOffice.org and an appropriate OpenOffice.org Software Development Kit (SDK). The minimal suggested version is OpenOffice.org 2.0.4. With earlier versions, some features of the plugin will not work.

*'''[http://download.openoffice.org OpenOffice.org]''' or '''[http://www.sun.com/staroffice StarOffice 8]''' or higher versions of both programs
*'''[http://download.openoffice.org/sdk.html OpenOffice.org Software Development Kit (SDK)]'''

Note that the versions of OpenOffice.org and the OpenOffice.org SDK must match for everything to work.

== Configuration ==
Before you can use the new project types you must configure the plugin because it needs an installed OpenOffice.org and OpenOffice.org SDK.

Note:
* As default settings, a standard installation will be found by the plugin - but only if OpenOffice.org together with the SDK are present.
* When you choose the OpenOffice.org installation and an appropriate SDK is found, that SDK is chosen, the "OpenOffice.org SDK Installation" field is then disabled.
* If you change the OpenOffice.org or OpenOffice.org SDK installation, these changes are effective for projects created from now on only.

For changing the office and SDK installation please choose
*'' '''Tools -> Options -> Miscellaneous -> OOo API plugin''' ''
and select a valid OpenOffice.org and OpenOffice.org SDK installation.
 [[Image:OpenOffice_Extensions_Plugin_Options.png|center]] 
The configuration step automatically installs a new OpenOffice.org library which can be used in other projects to support the OpenOffice.org API. Including this library in your own projects enables context sensitive help and code completion.

Note: on Debian/Ubuntu, the OpenOffice.org installation directory is <code>/usr/lib/openoffice/</code>. For other *nix platforms the location may vary, but you can find the location by inspecting the shell script <code>/usr/bin/ooffice</code> to see where the <code>ooqstart</code> executable is in your installation.

== Working with new Project Types ==
The plugin integrates four new project types under the category '''StarOffice/OpenOffice.org''':
*'''StarOffice/OpenOffice.org Add-On'''
*'''StarOffice/OpenOffice.org Calc Add-Ins'''
*'''StarOffice/OpenOffice.org Client Application'''
*'''StarOffice/OpenOffice.org Component'''

The wizards will collect the necessary information to create the new projects and should follow the NetBeans philosophy. You can simply choose
*'' '''File -> New Project -> OpenOffice.org -> <project_type>''' ''
For more details about the project types please take a look at
*[[OpenOffice_Simple_UNO_Client_Application_Project_Type|OpenOffice.org UNO Client Application Project Type]]
*[[OpenOffice_Calc_Add-In_Project_Type|OpenOffice.org Calc Add-In Project Type]]
*[[General_UNO_Component_Project_Type|OpenOffice.org Component Project Type]]
*[[OpenOffice_Add-On_Project_Type|OpenOffice.org Add-On Project Type]]

== Migrate Projects ==
To migrate projects from an older version of the plugin to a new one is not necessary - the plugin itself will take care of that: build-uno-impl.xml and the project-uno.properties are updated, when updated versions of these files are needed for new features of the updated plugin. Note that build-uno-impl.xml will be overwritten, but project-uno.properties not. In the properties file, only new entries are added, existing ones are kept as they are. The update of the files happens when an old project is opened with a new version of the plugin and for all opened projects when the new plugin is downloaded and installed.

When migrating from one Office version to another (or porting a project across platforms), only a library has to be changed, called "OpenOffice.org <version_number>" (or "StarOffice <version_number>"). Choose '''Tools -> Libraries''' to get an overview of the existing libraries. A library is created when a valid OpenOffice.org and OpenOffice.org SDK is selected in '''Tools -> Options -> Miscellaneous -> OOo API Plugin''' (See [[OpenOffice_NetBeans_Integration#Configuration|Configuration]] for more details).
* To change the library, click right on the project in the '''Project''' window and open the properties. Select '''Libraries''' as category and remove the one that points to the old installation and add the new one.
* When porting the project across platforms, NetBeans notifies that a reference problem exists. The steps for changing the libraries also help in this case.

== Known Problems and Missing Features ==

* Context sensitive help does not work on Linux (Solaris not yet tested), even the javadoc generated Java UNO runtime reference documentation does not work on Linux. Under Windows both work as expected.
* "Red Dot Problem": When you have created a project that supports own idl files (e.g. a Clac AddIn), a "clean" on the project will produce "red dots" that show that imported functionality is missing. The cause for this is the deleted jar file with the idl types that are used in your project. Although this does not seem to be the case, a compile will work and solve the problem. Sometimes the signs appear when "clean and build" is chosen - here the compiled idl files exist, but NetBeans does not recognize that. Open the offending Java file to solve that. Solution: compile idl files in the background and produce a "shadow" jar file in a temp directory that can be used even if the "official" file in the <project_name>/dist folder is deleted.
* With NetBeans versions at least 6.1 there is an update problem regarding NetBeans property sheets and node views: property sheet changes are not reflected in the node view. Seems like the notify mechanism for these updates has changed.

= Releases =

{|cellpadding=5 cellspacing=0 border=1 style="border-collapse:collapse; margin-left: 3em; border-color: #333;"
|- style="background-color: #DEDEDE;"
| Release Version || Planned Release Date || Release Date || Planned Features
|- align=center
| 1.0 || 05/08/07 || 05/08/07 || -
|- align=center
| 1.1 || 09/01/07 || 09/18/07 || [[OpenOffice_NetBeans_Integration/Releases/Release_1.1| see 1.1]]
|- align=center
| 1.1.1 || 03/08 || 03/20/08 || [[OpenOffice_NetBeans_Integration/Releases/Release_1.1.x| see 1.1.1]]
|- align=center
| 1.1.2 || 04/08 || 04/30/08 || [[OpenOffice_NetBeans_Integration/Releases/Release_1.1.x| see 1.1.2]]
|- align=center
| 1.1.3 || 06/30/08 || - || [[OpenOffice_NetBeans_Integration/Releases/Release_1.1.x| see 1.1.3]]
|- align=center
| 2.0 || 09/08 || - || [[OpenOffice_NetBeans_Integration/Releases/Release_2.0| see 2.0]]
|- align=center
| 2.0.3 || - || - || bugfixes only
|- align=center
| 2.0.4 || - || - || bugfixes only
|- align=center
| 2.0.5 || - || - || bugfixes only
|- align=center
| 2.0.6 || - || - || bugfixes only
|- align=center
| 2.0.7.alpha || - || - || changes to support NetBeans 6.9, opnly available in the file section of the API project, [http://api.openoffice.org/files/documents/22/4772/org-openoffice-extensions-2.0.7.alpha.nbm org-openoffice-extensions-2.0.7.alpha.nbm]
|}

:   Detailed download statistics can be found [[OpenOffice_NetBeans_Integration/Releases/Download_Statistic| here]] (not up-to-date)

* [[OpenOffice_NetBeans_Integration/Releases/Release_1.2#Current_issues_concerning_NetBeans_6|Issues]] for using the plugin with NetBeans 6.

= Planned Features =
The focus is on creating new wizards for various tasks plus common basic functionality. The main programming language is Java. Support for C++ is also planned and depends on the C++ support in NetBeans which will be available at least for NetBeans 6.0. The planned feature list is not final and more specialized wizards for other service provider interfaces (SPI) are coming in the future.

== New Project Types ==
*'''[[OpenOffice_Scripting_Project_Type|OpenOffice.org Scripting Project Type]]''' This new project type will create an adapted J2SE class library project with special support for OpenOffice.org scripting. It should provide you the possibility to import scripts from OpenOffice.org and open documents, edit, change and build these scripts, debug them and export them back (currently the support is planned for Java scripts only).
*'''[[OpenOffice_SmartTag_Project_Type|OpenOffice.org SmartTag Project Type]]''' This new project type will simplify the development of SmartTags for the OpenOffice.org Writer application.
*'''[[OpenOffice_API_Library_Wrapper_Project_Type|OpenOffice.org API Library API Wrapper Project Type]]''' This new project type should create a ''Library Wrapper Module'' to support simple usage of the OpenOffice.org API in your own projects. It bundles the necessary API jar files from OpenOffice.org in the library and in client applications. This of course is necessary to make use of the OpenOffice.org API in clients running on machines where no OpenOffice.org is installed and where the communication with OpenOffice.org is made over a remote socket connection.

== Common Features ==
*'''Editor for xcu files''' This must be defined in detail but we can think of a special editor for OpenOffice .org configuration files.

= Quality Assurance =

If you find bugs please submit a new [http://api.openoffice.org/issues/enter_bug.cgi?component=sdk&issue_type=DEFECT issue] in the category '''sdk''' and the subcomponent '''netbeans-integration'''

* [[OpenOffice_NetBeans_Integration_QA|Schedule for OpenOffice.org NetBeans Integration QA ]]

= Localization =
* [[OpenOffice_NetBeans_Integration/Localization|Localization Tutorial]]

= Things to be done =
* [[OpenOffice_NetBeans_Integration/To-Dos|ToDo list]]

= Feedback =
We will continuously extend and improve the plugin in the future and your feedback is welcome and highly appreciated. We would like to invite you to discuss it on [mailto:dev@api.openoffice.org dev@api.openoffice.org] (Note: you have to be subscribed on the mailing list).

You can also submit new [http://api.openoffice.org/issues/enter_bug.cgi?component=sdk&issue_type=FEATURE feature] or [http://api.openoffice.org/issues/enter_bug.cgi?component=sdk&issue_type=ENHANCEMENT enhancement] requests in the issue tracker in the category '''sdk''' and the subcomponent '''netbeans-integration'''

[[Category:NetBeans]]
[[Category:API]]
[[Category:Effort]]

OpenOffice NetBeans Integration

2014-07-08T12:31:37Z

Global667: Updating the installation rules to 4.1

[[image:OOo-Netbeans-Plugin.png|right]]
= Overview =
The OpenOffice.org API plugin for NetBeans simplifies the development of OpenOffice.org extensions. You can use the OpenOffice.org API to program OpenOffice.org, and automate remote or in process tasks extend OpenOffice.org with completely new functionality. The OpenOffice.org API plugin for NetBeans simplifies accessing and using of the API in new projects and simplifies the task of creating complete OpenOffice.org extension packages (comparable to the NetBeans plugin modules).

= Download and Installation =
The plugin appears automatically in Netbeans 6.5.x, 6.7.x, 6.8 (version 2.0.6) but is not listed for later versions.

The plugin is available for download from [http://people.apache.org/~cmarcum/devtools/ http://people.apache.org/~cmarcum/devtools/] provided by Carl Marcum. Use 3.x versions for extension development for OpenOffice.org versions 3.0 thru 3.4. Use the latest 4.0.5 alpha version for extension development for Apache OpenOffice 4.x. This version is under active development and will be made available in the NetBeans plugin manager list when finished. Until then, remember that it is an '''Beta''' version.

The configuration is self explanatory, for detailed information see [[OpenOffice_NetBeans_Integration#Configuration|Configuration]].

The source is available in the Apache OpenOffice.org source SVN repository in the '''devtools''' tree. The trunk is under development and the tagged 3.0.0.beta will build and run.
<blockquote>[https://svn.apache.org/repos/asf/openoffice/devtools/netbeansintegration/trunk https://svn.apache.org/repos/asf/openoffice/devtools/netbeansintegration/trunk]</blockquote>

== Build and install from source ==
The NetBeans-plugin for 4.1.0 is beta and you need to compile by hand. It seems that it doesn't support C++ development for now.
* Install NetBeans 8.0 from https://netbeans.org/downloads/ take "Java SE" or "All" Package
* Under NetBeans create a new SVN (anonymous) repository to <blockquote> https://svn.apache.org/repos/asf/openoffice/devtools/netbeansintegration/ </blockquote>
* Create a NBM from the project you get from SVN. On errors install the needed plugins like junit.
* Install the NBM

= Features =
Overview of the features included in the current plugin.
== Project Types ==
Click on "File" - "New Project..." and choose category "OpenOffice.org" to open a new project. All project types create working code. Once the project wizard is finished, a working
compilable project is created. It may not do anything, but it can be used
in OpenOffice.org from the beginning.

*'''[[OpenOffice_Simple_UNO_Client_Application_Project_Type|OpenOffice.org Client Application Project Type]]'''
This project type creates an adapted J2SE client application project with additional support of the
simple UNO bootstrap feature. To enable this, some pre-compiled glue code is bundled with the client
application. The result is a portable jar file that bootstraps OpenOffice.org on any supported OS.

*'''[[OpenOffice_Calc_Add-In_Project_Type|OpenOffice.org Calc Add-In Project Type]]'''
This project type creates an adapted J2SE class library project with special support for a UNO
component library and an office extension package. The wizard collects the necessary information for new
Calc built-in functions and abstracts from the underlying UNO technology.

*'''[[General_UNO_Component_Project_Type|General UNO Component Project Type]]'''
This project type creates an adapted J2SE class library project with special support for a
UNO component library and an OpenOffice.org extension package. The wizard collects information about services
and additional optional interfaces which should be implemented. Additional IDL types can also be
defined. A complete code skeleton is generated, with the component helper functions and the default interface methods already implemented.

*'''[[OpenOffice_Add-On_Project_Type|OpenOffice.org Add-On Project Type]]'''
This project type creates an adapted J2SE class library project with special support for a UNO
component library and an OpenOffice.org extension package. The wizard collects the necessary information for an
OpenOffice.org Add-On component and generates an Add-On specific code skeleton.

== File Types ==
Click on "File" - "New File..." and select "OpenOffice.org" as category to create a new file for an OpenOffice.org project. Note, that the OpenOffice.org category is available in all projects, although it only makes sense to use it in one of the projects stated above.
*'''xcu file type'''
Create an empty xcu file type. The files are recognized in NetBeans and
syntax highlighting is supported.

*'''xcs file type'''
Create an empty xcs file type. The files are recognized in NetBeans and
syntax highlighting is supported.

*'''UNO idl file type'''
You can use a file type wizard to create idl files. In the first step, you must select the name location
and UNO type (e.g. Service or Interface). You can add additional
information in the second step. When an interface is created, the second step asks about
the functions that the interface should contain. A complete working idl file is created, and NetBeans provides syntax highlighting. When you choose
to also create an implementation object (only available for service or interface), a Java skeleton file implementing
your new idl file will also be created.

*'''Java UNO Object file type'''
This file wizard creates a Java skeleton file that implements all functions defined in an interface or service idl file. If you choose a service, the Java implementation file will also be
registered in OpenOffice.org when your extension is deployed.

== Create, deploy and debug ==
These are actions that are available in the context menu of an extension project in the "Project"
view.

*'''Debug Extension in Target OpenOffice.org'''
If necessary, "Create OXT" is executed. The resulting OXT file is registered in a temporary user installation of OpenOffice.org, which is located in the build directory of the project. (Cleaning of the project removes the user installation again.) Then OpenOffice.org is started with this user installation. To trigger the registered extension, an appropriate action must be done in OpenOffice.org.
Execution stops at any breakpoints added to the code of the extension and debugging can start from there.

*'''Deploy and Run OpenOffice.org Extension'''
If necessary, "Create OXT" is executed. The resulting OXT file is registered inside the user installation of OpenOffice.org. Then OpenOffice.org is started.

*'''Create OXT'''
If necessary, your code is compiled. The resulting jar file is packed into an OXT file, together with other necessary files such as configuration files, a manifest file, and images. The OXT file is located in the "dist" directory of the project.

*'''Publish Extension on OpenOffice.org Website'''
The starting page for uploading and publishing your extension on api.services.openoffice.org is loaded in your default web browser.

== Miscellaneous ==
*'''External Jars'''
Additional external jars that are used in an extension are automatically copied into the OXT file and added to the extension's classpath. A registered extension in OpenOffice.org can still use the functionality provided there.
The jars can be added to the project as a single jar or as part of a NetBeans library. Note: All the jars from a library will be added to the OXT file, independent from their usage in the extension.

== Specifications ==

Find here links to the specifications of the plugin on the api.openoffice.org page.

[http://specs.openoffice.org/sdk/tools/spec_openoffice-netbeans-integration.odt OpenOffice.org Plugin for NetBeans]

[http://specs.openoffice.org/sdk/tools/spec_openoffice-netbeans-integration-addon-wizard.odt OpenOffice.org Plugin for NetBeans: Add-On Wizard]

[http://specs.openoffice.org/sdk/tools/spec_openoffice-netbeans-integration-calc-addin-wizard.odt OpenOffice.org Plugin for NetBeans: Add-In Wizard]

[http://specs.openoffice.org/sdk/tools/spec_openoffice-netbeans-integration-component-wizard.odt OpenOffice.org Plugin for NetBeans: Component Wizard]

[http://specs.openoffice.org/sdk/tools/spec_openoffice-netbeans-integration-debug-component.odt OpenOffice.org Plugin for NetBeans: Debug Feature]

[http://specs.openoffice.org/sdk/tools/spec_openoffice-netbeans-integration-new-idl-type.odt OpenOffice.org Plugin for NetBeans: IDL type support]

[http://specs.openoffice.org/sdk/tools/spec_openoffice-netbeans-integration-description-xml.odt OpenOffice.org Plugin for NetBeans: Support description.xml]

= Working with the plugin =
The following section describes how you can work with the plugin and describes the requirements because the plugin make use of some external stuff provided by an office and the OpenOffice.org SDK.

== Requirements ==
The plugin works only in combination with OpenOffice.org and an appropriate OpenOffice.org Software Development Kit (SDK). The minimal suggested version is OpenOffice.org 2.0.4. With earlier versions, some features of the plugin will not work.

*'''[http://download.openoffice.org OpenOffice.org]''' or '''[http://www.sun.com/staroffice StarOffice 8]''' or higher versions of both programs
*'''[http://download.openoffice.org/sdk.html OpenOffice.org Software Development Kit (SDK)]'''

Note that the versions of OpenOffice.org and the OpenOffice.org SDK must match for everything to work.

== Configuration ==
Before you can use the new project types you must configure the plugin because it needs an installed OpenOffice.org and OpenOffice.org SDK.

Note:
* As default settings, a standard installation will be found by the plugin - but only if OpenOffice.org together with the SDK are present.
* When you choose the OpenOffice.org installation and an appropriate SDK is found, that SDK is chosen, the "OpenOffice.org SDK Installation" field is then disabled.
* If you change the OpenOffice.org or OpenOffice.org SDK installation, these changes are effective for projects created from now on only.

For changing the office and SDK installation please choose
*'' '''Tools -> Options -> Miscellaneous -> OOo API plugin''' ''
and select a valid OpenOffice.org and OpenOffice.org SDK installation.
 [[Image:OpenOffice_Extensions_Plugin_Options.png|center]] 
The configuration step automatically installs a new OpenOffice.org library which can be used in other projects to support the OpenOffice.org API. Including this library in your own projects enables context sensitive help and code completion.

Note: on Debian/Ubuntu, the OpenOffice.org installation directory is <code>/usr/lib/openoffice/</code>. For other *nix platforms the location may vary, but you can find the location by inspecting the shell script <code>/usr/bin/ooffice</code> to see where the <code>ooqstart</code> executable is in your installation.

== Working with new Project Types ==
The plugin integrates four new project types under the category '''StarOffice/OpenOffice.org''':
*'''StarOffice/OpenOffice.org Add-On'''
*'''StarOffice/OpenOffice.org Calc Add-Ins'''
*'''StarOffice/OpenOffice.org Client Application'''
*'''StarOffice/OpenOffice.org Component'''

The wizards will collect the necessary information to create the new projects and should follow the NetBeans philosophy. You can simply choose
*'' '''File -> New Project -> OpenOffice.org -> <project_type>''' ''
For more details about the project types please take a look at
*[[OpenOffice_Simple_UNO_Client_Application_Project_Type|OpenOffice.org UNO Client Application Project Type]]
*[[OpenOffice_Calc_Add-In_Project_Type|OpenOffice.org Calc Add-In Project Type]]
*[[General_UNO_Component_Project_Type|OpenOffice.org Component Project Type]]
*[[OpenOffice_Add-On_Project_Type|OpenOffice.org Add-On Project Type]]

== Migrate Projects ==
To migrate projects from an older version of the plugin to a new one is not necessary - the plugin itself will take care of that: build-uno-impl.xml and the project-uno.properties are updated, when updated versions of these files are needed for new features of the updated plugin. Note that build-uno-impl.xml will be overwritten, but project-uno.properties not. In the properties file, only new entries are added, existing ones are kept as they are. The update of the files happens when an old project is opened with a new version of the plugin and for all opened projects when the new plugin is downloaded and installed.

When migrating from one Office version to another (or porting a project across platforms), only a library has to be changed, called "OpenOffice.org <version_number>" (or "StarOffice <version_number>"). Choose '''Tools -> Libraries''' to get an overview of the existing libraries. A library is created when a valid OpenOffice.org and OpenOffice.org SDK is selected in '''Tools -> Options -> Miscellaneous -> OOo API Plugin''' (See [[OpenOffice_NetBeans_Integration#Configuration|Configuration]] for more details).
* To change the library, click right on the project in the '''Project''' window and open the properties. Select '''Libraries''' as category and remove the one that points to the old installation and add the new one.
* When porting the project across platforms, NetBeans notifies that a reference problem exists. The steps for changing the libraries also help in this case.

== Known Problems and Missing Features ==

* Context sensitive help does not work on Linux (Solaris not yet tested), even the javadoc generated Java UNO runtime reference documentation does not work on Linux. Under Windows both work as expected.
* "Red Dot Problem": When you have created a project that supports own idl files (e.g. a Clac AddIn), a "clean" on the project will produce "red dots" that show that imported functionality is missing. The cause for this is the deleted jar file with the idl types that are used in your project. Although this does not seem to be the case, a compile will work and solve the problem. Sometimes the signs appear when "clean and build" is chosen - here the compiled idl files exist, but NetBeans does not recognize that. Open the offending Java file to solve that. Solution: compile idl files in the background and produce a "shadow" jar file in a temp directory that can be used even if the "official" file in the <project_name>/dist folder is deleted.
* With NetBeans versions at least 6.1 there is an update problem regarding NetBeans property sheets and node views: property sheet changes are not reflected in the node view. Seems like the notify mechanism for these updates has changed.

= Releases =

{|cellpadding=5 cellspacing=0 border=1 style="border-collapse:collapse; margin-left: 3em; border-color: #333;"
|- style="background-color: #DEDEDE;"
| Release Version || Planned Release Date || Release Date || Planned Features
|- align=center
| 1.0 || 05/08/07 || 05/08/07 || -
|- align=center
| 1.1 || 09/01/07 || 09/18/07 || [[OpenOffice_NetBeans_Integration/Releases/Release_1.1| see 1.1]]
|- align=center
| 1.1.1 || 03/08 || 03/20/08 || [[OpenOffice_NetBeans_Integration/Releases/Release_1.1.x| see 1.1.1]]
|- align=center
| 1.1.2 || 04/08 || 04/30/08 || [[OpenOffice_NetBeans_Integration/Releases/Release_1.1.x| see 1.1.2]]
|- align=center
| 1.1.3 || 06/30/08 || - || [[OpenOffice_NetBeans_Integration/Releases/Release_1.1.x| see 1.1.3]]
|- align=center
| 2.0 || 09/08 || - || [[OpenOffice_NetBeans_Integration/Releases/Release_2.0| see 2.0]]
|- align=center
| 2.0.3 || - || - || bugfixes only
|- align=center
| 2.0.4 || - || - || bugfixes only
|- align=center
| 2.0.5 || - || - || bugfixes only
|- align=center
| 2.0.6 || - || - || bugfixes only
|- align=center
| 2.0.7.alpha || - || - || changes to support NetBeans 6.9, opnly available in the file section of the API project, [http://api.openoffice.org/files/documents/22/4772/org-openoffice-extensions-2.0.7.alpha.nbm org-openoffice-extensions-2.0.7.alpha.nbm]
|}

:   Detailed download statistics can be found [[OpenOffice_NetBeans_Integration/Releases/Download_Statistic| here]] (not up-to-date)

* [[OpenOffice_NetBeans_Integration/Releases/Release_1.2#Current_issues_concerning_NetBeans_6|Issues]] for using the plugin with NetBeans 6.

= Planned Features =
The focus is on creating new wizards for various tasks plus common basic functionality. The main programming language is Java. Support for C++ is also planned and depends on the C++ support in NetBeans which will be available at least for NetBeans 6.0. The planned feature list is not final and more specialized wizards for other service provider interfaces (SPI) are coming in the future.

== New Project Types ==
*'''[[OpenOffice_Scripting_Project_Type|OpenOffice.org Scripting Project Type]]''' This new project type will create an adapted J2SE class library project with special support for OpenOffice.org scripting. It should provide you the possibility to import scripts from OpenOffice.org and open documents, edit, change and build these scripts, debug them and export them back (currently the support is planned for Java scripts only).
*'''[[OpenOffice_SmartTag_Project_Type|OpenOffice.org SmartTag Project Type]]''' This new project type will simplify the development of SmartTags for the OpenOffice.org Writer application.
*'''[[OpenOffice_API_Library_Wrapper_Project_Type|OpenOffice.org API Library API Wrapper Project Type]]''' This new project type should create a ''Library Wrapper Module'' to support simple usage of the OpenOffice.org API in your own projects. It bundles the necessary API jar files from OpenOffice.org in the library and in client applications. This of course is necessary to make use of the OpenOffice.org API in clients running on machines where no OpenOffice.org is installed and where the communication with OpenOffice.org is made over a remote socket connection.

== Common Features ==
*'''Editor for xcu files''' This must be defined in detail but we can think of a special editor for OpenOffice .org configuration files.

= Quality Assurance =

If you find bugs please submit a new [http://api.openoffice.org/issues/enter_bug.cgi?component=sdk&issue_type=DEFECT issue] in the category '''sdk''' and the subcomponent '''netbeans-integration'''

* [[OpenOffice_NetBeans_Integration_QA|Schedule for OpenOffice.org NetBeans Integration QA ]]

= Localization =
* [[OpenOffice_NetBeans_Integration/Localization|Localization Tutorial]]

= Things to be done =
* [[OpenOffice_NetBeans_Integration/To-Dos|ToDo list]]

= Feedback =
We will continuously extend and improve the plugin in the future and your feedback is welcome and highly appreciated. We would like to invite you to discuss it on [mailto:dev@api.openoffice.org dev@api.openoffice.org] (Note: you have to be subscribed on the mailing list).

You can also submit new [http://api.openoffice.org/issues/enter_bug.cgi?component=sdk&issue_type=FEATURE feature] or [http://api.openoffice.org/issues/enter_bug.cgi?component=sdk&issue_type=ENHANCEMENT enhancement] requests in the issue tracker in the category '''sdk''' and the subcomponent '''netbeans-integration'''

[[Category:NetBeans]]
[[Category:API]]
[[Category:Effort]]

OpenOffice NetBeans Integration

2014-07-08T12:22:06Z

Global667: /* Download and Installation */ add Ooo 4.1 and Netbeans 8.0 support

[[image:OOo-Netbeans-Plugin.png|right]]
= Overview =
The OpenOffice.org API plugin for NetBeans simplifies the development of OpenOffice.org extensions. You can use the OpenOffice.org API to program OpenOffice.org, and automate remote or in process tasks extend OpenOffice.org with completely new functionality. The OpenOffice.org API plugin for NetBeans simplifies accessing and using of the API in new projects and simplifies the task of creating complete OpenOffice.org extension packages (comparable to the NetBeans plugin modules).

= Download and Installation =
The plugin appears automatically in Netbeans 6.5.x, 6.7.x, 6.8 (version 2.0.6) but is not listed for later versions.

The plugin is available for download from [http://people.apache.org/~cmarcum/devtools/ http://people.apache.org/~cmarcum/devtools/] provided by Carl Marcum. Use 3.x versions for extension development for OpenOffice.org versions 3.0 thru 3.4. Use the latest 4.0.5 alpha version for extension development for Apache OpenOffice 4.x. This version is under active development and will be made available in the NetBeans plugin manager list when finished. Until then, remember that it is an '''Beta''' version.

The configuration is self explanatory, for detailed information see [[OpenOffice_NetBeans_Integration#Configuration|Configuration]].

The source is available in the Apache OpenOffice.org source SVN repository in the '''devtools''' tree. The trunk is under development and the tagged 3.0.0.beta will build and run.
<blockquote>[https://svn.apache.org/repos/asf/openoffice/devtools/netbeansintegration/trunk https://svn.apache.org/repos/asf/openoffice/devtools/netbeansintegration/trunk]</blockquote>

== Download and install for NetBeans 8.0 and OpenOffice 4.1.0 ==
The NetBeans-plugin is beta and you need to compile by hand. It seems that it doesn't support C++ development for now.
* Install NetBeans 8.0 from https://netbeans.org/downloads/ take Java SE or All Package
* Under NetBeans create a new SVN (anonymous) repository to https://svn.apache.org/repos/asf/openoffice/devtools/netbeansintegration/
* Open the Project make Clean/Build. On errors install the needed plugins like junit.
* Create a NBM and install it

= Build and Install from Source =
There is a tagged version of 3.0.0.beta in the SVN repository. To checkout this version using subversion to a directory aoo-netbeans:
<blockquote>
svn co http://svn.apache.org/repos/asf/openoffice/devtools/netbeansintegration/tags/3.0.0.beta aoo-netbeans
</blockquote>

Start Netbeans 7.x then select File -> Open Project and navigate to the aoo-netbeans directory the source was checked out to. 
In the projects window RMB on project -> Create NBM. The .nbm file will be located in the build sub-directory of the project. 
Select Tools -> Plugins and select Downloaded Tab -> Add and select org-openoffice-extensions.nbm from project build directory then check box and Install.

Setup AOO Installation and SDK Settings below are still valid.

= Features =
Overview of the features included in the current plugin.
== Project Types ==
Click on "File" - "New Project..." and choose category "OpenOffice.org" to open a new project. All project types create working code. Once the project wizard is finished, a working
compilable project is created. It may not do anything, but it can be used
in OpenOffice.org from the beginning.

*'''[[OpenOffice_Simple_UNO_Client_Application_Project_Type|OpenOffice.org Client Application Project Type]]'''
This project type creates an adapted J2SE client application project with additional support of the
simple UNO bootstrap feature. To enable this, some pre-compiled glue code is bundled with the client
application. The result is a portable jar file that bootstraps OpenOffice.org on any supported OS.

*'''[[OpenOffice_Calc_Add-In_Project_Type|OpenOffice.org Calc Add-In Project Type]]'''
This project type creates an adapted J2SE class library project with special support for a UNO
component library and an office extension package. The wizard collects the necessary information for new
Calc built-in functions and abstracts from the underlying UNO technology.

*'''[[General_UNO_Component_Project_Type|General UNO Component Project Type]]'''
This project type creates an adapted J2SE class library project with special support for a
UNO component library and an OpenOffice.org extension package. The wizard collects information about services
and additional optional interfaces which should be implemented. Additional IDL types can also be
defined. A complete code skeleton is generated, with the component helper functions and the default interface methods already implemented.

*'''[[OpenOffice_Add-On_Project_Type|OpenOffice.org Add-On Project Type]]'''
This project type creates an adapted J2SE class library project with special support for a UNO
component library and an OpenOffice.org extension package. The wizard collects the necessary information for an
OpenOffice.org Add-On component and generates an Add-On specific code skeleton.

== File Types ==
Click on "File" - "New File..." and select "OpenOffice.org" as category to create a new file for an OpenOffice.org project. Note, that the OpenOffice.org category is available in all projects, although it only makes sense to use it in one of the projects stated above.
*'''xcu file type'''
Create an empty xcu file type. The files are recognized in NetBeans and
syntax highlighting is supported.

*'''xcs file type'''
Create an empty xcs file type. The files are recognized in NetBeans and
syntax highlighting is supported.

*'''UNO idl file type'''
You can use a file type wizard to create idl files. In the first step, you must select the name location
and UNO type (e.g. Service or Interface). You can add additional
information in the second step. When an interface is created, the second step asks about
the functions that the interface should contain. A complete working idl file is created, and NetBeans provides syntax highlighting. When you choose
to also create an implementation object (only available for service or interface), a Java skeleton file implementing
your new idl file will also be created.

*'''Java UNO Object file type'''
This file wizard creates a Java skeleton file that implements all functions defined in an interface or service idl file. If you choose a service, the Java implementation file will also be
registered in OpenOffice.org when your extension is deployed.

== Create, deploy and debug ==
These are actions that are available in the context menu of an extension project in the "Project"
view.

*'''Debug Extension in Target OpenOffice.org'''
If necessary, "Create OXT" is executed. The resulting OXT file is registered in a temporary user installation of OpenOffice.org, which is located in the build directory of the project. (Cleaning of the project removes the user installation again.) Then OpenOffice.org is started with this user installation. To trigger the registered extension, an appropriate action must be done in OpenOffice.org.
Execution stops at any breakpoints added to the code of the extension and debugging can start from there.

*'''Deploy and Run OpenOffice.org Extension'''
If necessary, "Create OXT" is executed. The resulting OXT file is registered inside the user installation of OpenOffice.org. Then OpenOffice.org is started.

*'''Create OXT'''
If necessary, your code is compiled. The resulting jar file is packed into an OXT file, together with other necessary files such as configuration files, a manifest file, and images. The OXT file is located in the "dist" directory of the project.

*'''Publish Extension on OpenOffice.org Website'''
The starting page for uploading and publishing your extension on api.services.openoffice.org is loaded in your default web browser.

== Miscellaneous ==
*'''External Jars'''
Additional external jars that are used in an extension are automatically copied into the OXT file and added to the extension's classpath. A registered extension in OpenOffice.org can still use the functionality provided there.
The jars can be added to the project as a single jar or as part of a NetBeans library. Note: All the jars from a library will be added to the OXT file, independent from their usage in the extension.

== Specifications ==

Find here links to the specifications of the plugin on the api.openoffice.org page.

[http://specs.openoffice.org/sdk/tools/spec_openoffice-netbeans-integration.odt OpenOffice.org Plugin for NetBeans]

[http://specs.openoffice.org/sdk/tools/spec_openoffice-netbeans-integration-addon-wizard.odt OpenOffice.org Plugin for NetBeans: Add-On Wizard]

[http://specs.openoffice.org/sdk/tools/spec_openoffice-netbeans-integration-calc-addin-wizard.odt OpenOffice.org Plugin for NetBeans: Add-In Wizard]

[http://specs.openoffice.org/sdk/tools/spec_openoffice-netbeans-integration-component-wizard.odt OpenOffice.org Plugin for NetBeans: Component Wizard]

[http://specs.openoffice.org/sdk/tools/spec_openoffice-netbeans-integration-debug-component.odt OpenOffice.org Plugin for NetBeans: Debug Feature]

[http://specs.openoffice.org/sdk/tools/spec_openoffice-netbeans-integration-new-idl-type.odt OpenOffice.org Plugin for NetBeans: IDL type support]

[http://specs.openoffice.org/sdk/tools/spec_openoffice-netbeans-integration-description-xml.odt OpenOffice.org Plugin for NetBeans: Support description.xml]

= Working with the plugin =
The following section describes how you can work with the plugin and describes the requirements because the plugin make use of some external stuff provided by an office and the OpenOffice.org SDK.

== Requirements ==
The plugin works only in combination with OpenOffice.org and an appropriate OpenOffice.org Software Development Kit (SDK). The minimal suggested version is OpenOffice.org 2.0.4. With earlier versions, some features of the plugin will not work.

*'''[http://download.openoffice.org OpenOffice.org]''' or '''[http://www.sun.com/staroffice StarOffice 8]''' or higher versions of both programs
*'''[http://download.openoffice.org/sdk.html OpenOffice.org Software Development Kit (SDK)]'''

Note that the versions of OpenOffice.org and the OpenOffice.org SDK must match for everything to work.

== Configuration ==
Before you can use the new project types you must configure the plugin because it needs an installed OpenOffice.org and OpenOffice.org SDK.

Note:
* As default settings, a standard installation will be found by the plugin - but only if OpenOffice.org together with the SDK are present.
* When you choose the OpenOffice.org installation and an appropriate SDK is found, that SDK is chosen, the "OpenOffice.org SDK Installation" field is then disabled.
* If you change the OpenOffice.org or OpenOffice.org SDK installation, these changes are effective for projects created from now on only.

For changing the office and SDK installation please choose
*'' '''Tools -> Options -> Miscellaneous -> OOo API plugin''' ''
and select a valid OpenOffice.org and OpenOffice.org SDK installation.
 [[Image:OpenOffice_Extensions_Plugin_Options.png|center]] 
The configuration step automatically installs a new OpenOffice.org library which can be used in other projects to support the OpenOffice.org API. Including this library in your own projects enables context sensitive help and code completion.

Note: on Debian/Ubuntu, the OpenOffice.org installation directory is <code>/usr/lib/openoffice/</code>. For other *nix platforms the location may vary, but you can find the location by inspecting the shell script <code>/usr/bin/ooffice</code> to see where the <code>ooqstart</code> executable is in your installation.

== Working with new Project Types ==
The plugin integrates four new project types under the category '''StarOffice/OpenOffice.org''':
*'''StarOffice/OpenOffice.org Add-On'''
*'''StarOffice/OpenOffice.org Calc Add-Ins'''
*'''StarOffice/OpenOffice.org Client Application'''
*'''StarOffice/OpenOffice.org Component'''

The wizards will collect the necessary information to create the new projects and should follow the NetBeans philosophy. You can simply choose
*'' '''File -> New Project -> OpenOffice.org -> <project_type>''' ''
For more details about the project types please take a look at
*[[OpenOffice_Simple_UNO_Client_Application_Project_Type|OpenOffice.org UNO Client Application Project Type]]
*[[OpenOffice_Calc_Add-In_Project_Type|OpenOffice.org Calc Add-In Project Type]]
*[[General_UNO_Component_Project_Type|OpenOffice.org Component Project Type]]
*[[OpenOffice_Add-On_Project_Type|OpenOffice.org Add-On Project Type]]

== Migrate Projects ==
To migrate projects from an older version of the plugin to a new one is not necessary - the plugin itself will take care of that: build-uno-impl.xml and the project-uno.properties are updated, when updated versions of these files are needed for new features of the updated plugin. Note that build-uno-impl.xml will be overwritten, but project-uno.properties not. In the properties file, only new entries are added, existing ones are kept as they are. The update of the files happens when an old project is opened with a new version of the plugin and for all opened projects when the new plugin is downloaded and installed.

When migrating from one Office version to another (or porting a project across platforms), only a library has to be changed, called "OpenOffice.org <version_number>" (or "StarOffice <version_number>"). Choose '''Tools -> Libraries''' to get an overview of the existing libraries. A library is created when a valid OpenOffice.org and OpenOffice.org SDK is selected in '''Tools -> Options -> Miscellaneous -> OOo API Plugin''' (See [[OpenOffice_NetBeans_Integration#Configuration|Configuration]] for more details).
* To change the library, click right on the project in the '''Project''' window and open the properties. Select '''Libraries''' as category and remove the one that points to the old installation and add the new one.
* When porting the project across platforms, NetBeans notifies that a reference problem exists. The steps for changing the libraries also help in this case.

== Known Problems and Missing Features ==

* Context sensitive help does not work on Linux (Solaris not yet tested), even the javadoc generated Java UNO runtime reference documentation does not work on Linux. Under Windows both work as expected.
* "Red Dot Problem": When you have created a project that supports own idl files (e.g. a Clac AddIn), a "clean" on the project will produce "red dots" that show that imported functionality is missing. The cause for this is the deleted jar file with the idl types that are used in your project. Although this does not seem to be the case, a compile will work and solve the problem. Sometimes the signs appear when "clean and build" is chosen - here the compiled idl files exist, but NetBeans does not recognize that. Open the offending Java file to solve that. Solution: compile idl files in the background and produce a "shadow" jar file in a temp directory that can be used even if the "official" file in the <project_name>/dist folder is deleted.
* With NetBeans versions at least 6.1 there is an update problem regarding NetBeans property sheets and node views: property sheet changes are not reflected in the node view. Seems like the notify mechanism for these updates has changed.

= Releases =

{|cellpadding=5 cellspacing=0 border=1 style="border-collapse:collapse; margin-left: 3em; border-color: #333;"
|- style="background-color: #DEDEDE;"
| Release Version || Planned Release Date || Release Date || Planned Features
|- align=center
| 1.0 || 05/08/07 || 05/08/07 || -
|- align=center
| 1.1 || 09/01/07 || 09/18/07 || [[OpenOffice_NetBeans_Integration/Releases/Release_1.1| see 1.1]]
|- align=center
| 1.1.1 || 03/08 || 03/20/08 || [[OpenOffice_NetBeans_Integration/Releases/Release_1.1.x| see 1.1.1]]
|- align=center
| 1.1.2 || 04/08 || 04/30/08 || [[OpenOffice_NetBeans_Integration/Releases/Release_1.1.x| see 1.1.2]]
|- align=center
| 1.1.3 || 06/30/08 || - || [[OpenOffice_NetBeans_Integration/Releases/Release_1.1.x| see 1.1.3]]
|- align=center
| 2.0 || 09/08 || - || [[OpenOffice_NetBeans_Integration/Releases/Release_2.0| see 2.0]]
|- align=center
| 2.0.3 || - || - || bugfixes only
|- align=center
| 2.0.4 || - || - || bugfixes only
|- align=center
| 2.0.5 || - || - || bugfixes only
|- align=center
| 2.0.6 || - || - || bugfixes only
|- align=center
| 2.0.7.alpha || - || - || changes to support NetBeans 6.9, opnly available in the file section of the API project, [http://api.openoffice.org/files/documents/22/4772/org-openoffice-extensions-2.0.7.alpha.nbm org-openoffice-extensions-2.0.7.alpha.nbm]
|}

:   Detailed download statistics can be found [[OpenOffice_NetBeans_Integration/Releases/Download_Statistic| here]] (not up-to-date)

* [[OpenOffice_NetBeans_Integration/Releases/Release_1.2#Current_issues_concerning_NetBeans_6|Issues]] for using the plugin with NetBeans 6.

= Planned Features =
The focus is on creating new wizards for various tasks plus common basic functionality. The main programming language is Java. Support for C++ is also planned and depends on the C++ support in NetBeans which will be available at least for NetBeans 6.0. The planned feature list is not final and more specialized wizards for other service provider interfaces (SPI) are coming in the future.

== New Project Types ==
*'''[[OpenOffice_Scripting_Project_Type|OpenOffice.org Scripting Project Type]]''' This new project type will create an adapted J2SE class library project with special support for OpenOffice.org scripting. It should provide you the possibility to import scripts from OpenOffice.org and open documents, edit, change and build these scripts, debug them and export them back (currently the support is planned for Java scripts only).
*'''[[OpenOffice_SmartTag_Project_Type|OpenOffice.org SmartTag Project Type]]''' This new project type will simplify the development of SmartTags for the OpenOffice.org Writer application.
*'''[[OpenOffice_API_Library_Wrapper_Project_Type|OpenOffice.org API Library API Wrapper Project Type]]''' This new project type should create a ''Library Wrapper Module'' to support simple usage of the OpenOffice.org API in your own projects. It bundles the necessary API jar files from OpenOffice.org in the library and in client applications. This of course is necessary to make use of the OpenOffice.org API in clients running on machines where no OpenOffice.org is installed and where the communication with OpenOffice.org is made over a remote socket connection.

== Common Features ==
*'''Editor for xcu files''' This must be defined in detail but we can think of a special editor for OpenOffice .org configuration files.

= Quality Assurance =

If you find bugs please submit a new [http://api.openoffice.org/issues/enter_bug.cgi?component=sdk&issue_type=DEFECT issue] in the category '''sdk''' and the subcomponent '''netbeans-integration'''

* [[OpenOffice_NetBeans_Integration_QA|Schedule for OpenOffice.org NetBeans Integration QA ]]

= Localization =
* [[OpenOffice_NetBeans_Integration/Localization|Localization Tutorial]]

= Things to be done =
* [[OpenOffice_NetBeans_Integration/To-Dos|ToDo list]]

= Feedback =
We will continuously extend and improve the plugin in the future and your feedback is welcome and highly appreciated. We would like to invite you to discuss it on [mailto:dev@api.openoffice.org dev@api.openoffice.org] (Note: you have to be subscribed on the mailing list).

You can also submit new [http://api.openoffice.org/issues/enter_bug.cgi?component=sdk&issue_type=FEATURE feature] or [http://api.openoffice.org/issues/enter_bug.cgi?component=sdk&issue_type=ENHANCEMENT enhancement] requests in the issue tracker in the category '''sdk''' and the subcomponent '''netbeans-integration'''

[[Category:NetBeans]]
[[Category:API]]
[[Category:Effort]]

SDKInstallation

2014-07-08T02:40:26Z

Global667: /* Installation under Mac OS X */ grammar

{{Documentation/Banner}}
{{Documentation/NeedsRework}}
= How to install the SDK and compile the C++ examples =

For both Linux and Windows the following points are very important if you want to succeed in building C++ components and snippets:
* you need to have OpenOffice.org 1.1.0 or higher installed (SDK won't run without it)
* you need to install the SDK into a directory other than the one of the OOo application

== Installation under Mac OS X ==
{{Documentation/OSX|
The text below describes the installation of the SDK 4.1.0 and OpenOffice 4.1.0 on Mac OS X 10.9.4 with Xcode 4.1.1. It would works for other Intel Mac configurations too.
* Install Xcode. You can get it from the Apple App Store. Perhaps you must be registered as Mac developer under https://developer.apple.com
* Install newest OpenOffice and the corresponding SDK from http://openoffice.apache.org/downloads.html (Choose MacOS_x86-64)
* (Optional) Install MacPorts from http://www.macports.org. You need MacPorts to install optional Unix-like software needed by the SDK.
* Test the SDK. Open a terminal and look for the SDK folder. Now type and run:
<pre>
cd <SDK_Folder>
./setsdkenv_unix # Need to run every time before you use the SDK
cd examples/cpp/DocumentLoader
make
soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager" &
make DocumentLoader.run
</pre>
If everything went fine, you should see a new document, with the content of <SDK_Folder>/examples/cpp/DocumentLoader/test.odt.

Further informations see: http://www.openoffice.org/api/SDK/ and [[Documentation/DevGuide]]

Its recommended to use Eclipse or Netbeans to develop with OpenOffice SDK. There are plugins for booth.
For Eclipse visit [[OpenOffice_Eclipse_Integration]].
For Netbeans visit [[OpenOffice_NetBeans_Integration]].
}}

== Installation under LINUX ==
{{Documentation/Linux|
The text below describe the installation of the SDK 1.1.0 for OpenOffice.org1.1.0

The Software Development Kit (SDK) works on the top of an existing Openoffice.org installation because of using the same libraries. The SDK requires an Openoffice.org installation.
Even if you don't plan to use Java it is strongly recommended to install the JDK (1.4.1_01 or higher for OOo 1.1 SDK)
Of course a C++ compiler is needed (3.0.1 or higher). GNU make (3.79.1 or higher) is also essential.
When ready, launch :
<pre>
tar xzvf Ooo_1.1.0_LinuxIntel_sdk.tar.gz
</pre>

and go to the new created directory (in this example OpenOffice.org1.1_SDK) and launch the configure script which asks you relevant directories. We give here among others :
* where is your OpenOffice.org installed ? (for me /usr/lib/openoffice : noted <Ooo> later)
* Where is your Java SDK installed ? (for me /usr/java/j2sdk1.4.2_04)

Now you are ready to use the SDK. Every time you want to use it you have to launch the setsdkenv_unix script for environment variables. Automating this is not a problem under UNIX.

From now on, we will always note the SDK directory installation as : <OpenOffice.org1.1_SDK>. Please don't confuse with <Ooo> which is the openoffice.org /program/ directory.

You can find a little complement of this chapter in <OpenOffice.org1.1_SDK>/docs/install.html

The OOo2.0SDK installation is done also by launching the setsdkenv_unix script but asking more information :
<pre>
************************************************************************
*
* SDK environment is prepared for Linux
*
* SDK = /home/smoutou/openoffice.org2.0_sdk
* Office = /opt/openoffice.org2.0
* URE =
* Make = /usr/bin
* Zip = /usr/bin
* C++ Compiler = /usr/bin
* Java = /usr/java/j2sdk1.4.2_04
* Special Output directory = /home/smoutou
* Auto deployment = YES
*
************************************************************************
</pre>
If you want to check the Cpp examples, you have to launch first (as mentioned before)
<pre>
./setsdkenv_unix
</pre>
in your shell and then
<pre>
<Ooo>/program/soffice "-accept=socket,host=localhost,port=8100;urp;StarOffice.ServiceManager"
</pre>
For Openoffice.org 2.x, run instead:
<pre>
<Ooo>/program/soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager"
</pre>
Now Openoffice.org is listening on UNO connections through the network (here from localhost only).
We are ready to compile our first example and to check if it works correctly. For that we go in
<OpenOffice.org1.1_SDK>/examples/cpp/DocumentLoader directory.
<pre>
make
</pre>
will compile the example, and
<pre>
make DocumentLoader.run
</pre>
will launch the example. This example only load a Ooowriter's file (test.sxw) provided with the SDK.

Bear in mind the easier way to construct the examples of the SDK is to use the makefiles provided. When you are a beginner with the SDK you always underestimate important steps : for example the registry step discussed later. I estimate to have understand something when I am able to construct it starting with nothing (but skills). In the case of SDK this will take me a long time (and probably will not be finished). Then I can give you an advice : if you want to start a project, begin with modifying an example of the SDK.

Other SDK's examples are discussed later, but you can have a look to :

*[[Counter_Example|Counter example]]

}}

== Installation under Solaris ==
{{Documentation/Linux|
The text below describe the installation of the OpenOffic.org SDK 3.1 for OpenOffice.org3.1

The Software Development Kit (SDK) works on the top of an existing Openoffice.org installation because of using the same libraries. The SDK requires an Openoffice.org installation (default installation directory for Solaris is /opt/openoffice.org/ and /opt/openoffice.org3/)

Depending on which language you wish to use, you will need either:
The Java SDK which can be obtained [http://java.sun.com/javase/downloads/index.jsp here].
Or a C++ complier (g++ 3.0.1 or higher is recommended). As well as GNU make (3.79.1 or higher) is also essential.

First download the Solaris SDK from [http://download.openoffice.org/sdk/index.html here].

Now run the install script by typing the following command. This script will prompt you for a temporary directory where it will extract the installation package. Just press enter and the package will be extracted into the directory shown in brackets (in this case /var/tmp/unpack_openofficeorg). If you wish to extract the package into a separate directory, type in the full directory path at the prompt.

<pre>
# sh OOo-SDK_3.1.1_SolarisSparc_install_en-US.sh
Select the directory in which to save the unpacked files. [/var/tmp/unpack_openofficeorg]

File is being checked for errors ...
Unpacking ...
All files have been successfully unpacked.
</pre>

Now navigate into the packages directory under the unpacked installation directory that was just created.

<pre>
# cd /var/tmp/unpack_openofficeorg/packages
</pre>

Go ahead an install the SDK package using pfexec.

<pre>
# pfexec pkgadd -d .
</pre>

To check if the installation succeeded, attempt to navigate into the sdk directory under the OpenOffic.org basis directory.
<pre>
# cd /opt/openoffice.org/basis3.1/sdk
# ls
bin/ examples/ setsdkenv_unix.csh.in
classes/ idl/ setsdkenv_unix.sh.in
config.guess include/ settings/
config.sub index.html share/
configure.pl lib/
docs/ setsdkenv_unix
</pre>

Now you are ready to use the SDK. Every time you want to use it you have to launch the setsdkenv_unix script for environment variables. Automating this is not a problem under UNIX. You can find a little complement of this chapter in <OpenOffice.org1.1_SDK>/docs/install.html

In order to use the SDK you need to first execute the setsdkevn_unx script in the <OpenOffice.org>/basis3.1/sdk directory (/opt/openoffice.org/basis3.1/sdk for me). Before you execute this script, you need to locate all of the development tools for the language you will be using. Below is a list of the tools that the script prompts for and the locations of the tools on my machine.

<pre>
OpenOffice.org3 installation = /opt/openoffice.org3
GNU make 3.79.1 or higher = /usr/bin
C++ compiler (g++ 3.0.1 or higher) = /usr/bin
Zip = /usr/bin
Java = /usr/jdk/latest/
</pre>

Input the paths to your development tools when prompted.

You are now ready to use the OpenOffice SDK
}}

== Installation under Windows ==
{{Documentation/Windows|

You need a compiler out of the Microsoft Visual Studio family (other compilers like MinGW have turned out to be hard to configure for OOo on Windows).
The first thing after having installed the SDK is to launch the configureWindowsNT.bat and set all the necessary directories for proper use of the SDK.
If that has been done you have already installed everything, but *wait* one very important thing you should still know of:
Every time you want to run your own code or one of the SDK examples you need to launch the setsdkenv_Windows batch file from your command shell. The title of it should now be "Shell prepared for SDK". Happy coding, compiling and building now (I tell you it's easy from now on!).
GanescuCarmen describes some problems he encounter when trying SDK examples under Windows :
“I also use the 1.1 OO version.

I had a lots of problems.
Finally I succeeded to obtain the the header files, and in VC I needed some library to be included into project and some files(uno.idl) to be added to rdb files.
It was very hard to understand what it means registry(the rdb file not the Registry itself).

I was expecting to register something in Registry but it wasn't like this.
And with the service manager I had some problems, with the port, because the connection with 8100 port was not done.
I had to modify a file and to add some code for 8100 port.

But I did it and it works now.”
}}

=== Installing with the free MS Visual C++ Toolkit 2003 ===
{{Documentation/HelpNeeded|This section needs help for update because '''MS Visual C++ Toolkit 2003''' seems no more available. Please have a look at Microsoft for the free Visual C++ tools at the moment.}}
I have installed DevCpp to have a make executable file.
I have downloaded the free Visual C++ Toolkit 2003 here :
http://www.microsoft.com/downloads/details.aspx?FamilyID=272be09d-40bb-49fd-9cb0-4bfa122fa91b&displaylang=en

and then I have installed it. '''(This link is broken.)'''

I launch first C:\openoffice\OpenOffice.org2.0_SDK\configureWindowsNT.bat
which asks any questions :
<pre>
set OO_SDK_HOME=C:\openoffice\OpenOffice.org2.0_SDK
set OFFICE_HOME=C:\Program Files\OpenOffice.org 2.0
set OO_SDK_MAKE_HOME=C:\Dev-C++\Bin
set OO_SDK_CPP_HOME=C:\Program Files\Microsoft Visual C++ Toolkit 2003\Bin
set OO_SDK_JAVA_HOME=C:\Program Files\Java\jdk1.5.0_03
</pre>

and I am ready to launch setsdkenv_windows.bat

I have modified the following file :
C:\openoffice\OpenOffice.org2.0_SDK\examples\DevelopersGuide\ProfUNO\CppBinding\office_connect.cxx
to change the port accordingly to what OOo is listening.

I have modified the makefile :
added :
<pre>
CC_INCLUDES = -I"C:\Program Files\Microsoft Visual C++ Toolkit 2003\include" \
-I"C:\openoffice\OpenOffice.org2.0_SDK\include"
</pre>

and added libraries too :

<pre>
$(OUT_BIN)/%$(EXE_EXT) : $(SAMPLE_OBJ_OUT)/%.$(OBJ_EXT)
-$(MKDIR) $(subst /,$(PS),$(@D))
-$(MKDIR) $(subst /,$(PS),$(SAMPLE_GEN_OUT))
ifeq "$(OS)" "WIN"
$(LINK) $(EXE_LINK_FLAGS) /OUT:$@ /MAP:$(SAMPLE_GEN_OUT)/$(subst $(EXE_EXT),.map,$(@F)) \
$< $(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB)\
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libcp.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libc.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\oldnames.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\kernel32.lib"
else
$(LINK) $(EXE_LINK_FLAGS) $(LINK_LIBS) -o $@ $< \
$(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB) $(STDC++LIB)
endif
</pre>
I suppose there is a more straightforward way to add these libraries with adding the corresponding include path but I am unable to do that with VC++.

I find a solution of the previous problem three weeks later. My problem comes in fact from a bug in setsdkenv_windows.bat. A little correction in the file setsdkenv_windows.bat makes it possible to avoid the makefile modifications :
Put :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "C:\Program Files\Microsoft Visual C++ Toolkit 2003\VCVARS32.bat"
</pre>

instead of :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "%OO_SDK_CPP_HOME%\VCVARS32.bat"
</pre>
I think
<pre>
%OO_SDK_CPP_HOME%\..\VCVARS32.bat
</pre>
could work too (but not checked). You can also move vcvars32.bat in %OO_SDK_CPP_HOME%
("C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin" for me).

=== Other Windows Installations descriptions ===

You can find in [http://www.oooforum.org/forum/viewtopic.phtml?t=23772 OOoForum] a post entitled Guide for develop OpenOffice apps with VC++ .net (by [[CppSDKAuthors|LarsB]])

1.Download and install OpenOffice.

2.Download and install OpenOffice SDK

3.Create a new folder inludecpp in <oo_sdk_path>

4.Open Dos console change directory to <oo_sdk_path>\windows\bin

4.1 run cppumaker with followig paramerers
<pre>
cppumaker -BUCR -O <oo_sdk_path>\includecpp <office_programm_dir>\types.rdb
</pre>
or better with
<pre>
cppumaker -Gc -BUCR -O<includes_path> <ooffice_path>\URE\misc\types.rdb <ooffice_path>\Basis\program\offapi.rdb
</pre>
in recent versions.

(Attention: If you recieve a init error, copy types.rdb into the <oo_sdk_path>\windows\bin folder!)
After that all hpp and hdl files should be created in <oo_sdk_path>\includecpp

5.Open Visual Studio and create a new Win32 Console Application.
Applay the following changes to your project.

5.1. Tools ->Options->Projects->VC++ Directories -> Include Files
Add \include directory and <oo_sdk_path>\includecpp

5.2. Tools ->Options->Projects->VC++ Directories -> Library files
Add <oo_sdk_path>\windows\lib directory

5.3. Tools ->Options->Projects->VC++ Directories -> Executable files
Add <office_programm_dir>\program directory (location where you installed the version of the OpenOffice)

5.4 Open the Project Settings

5.4.1 Change Configuration to all All Configurations (the combobox in the left corner of the window)

5.4.2 Add the additional libraries

Properties->Linker->ComandLine in the Additional Options tab the library files
isal.lib icppu.lib icppuhelper.lib isal.lib isalhelper.lib ireg.lib irmcxt.lib stlport_vc71.lib

6.(example) Add the DocumentLoader.cxx from the cpp examples of the sdk
and compile. The source should compile without errors.

INFO : If you got the following error have a look at the solution 2 postings above!
Up to now, with the steps above i got the following error, when i run the DocumentLoader example.
The error is thrown, when the prog execution reach the following line:

<pre>

Reference< XSimpleRegistry > xSimpleRegistry( ::cppu::createSimpleRegistry() );
</pre>

with error shown below :

<pre>
Error:
Window title: Microsoft Visual C++ Debug Library
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

If somebody has experience with this kind of error it will be nice if he could
post a solution. So that here is a complete little guide for OpenOffice with VC++ .NET

Regards
[[CppSDKAuthors|Lars]]

[[CppSDKAuthors|François]] has improved the complete procedure with remarks :
Following all the steps I (_francois_) encountered two problems

* first in point 4.4.2

But there I guess it's because the procedure was meant for SDK 2 and I'm using SDK 1.1
The stlport_vc71.lib which you must include is distributed with the SDK 2 in the SDK 1.1 stlport_vc7.lib
you just need to include the stlport_vc7.lib instead of stlport_vc71.lib

* second problem after successfuly compiling the DocumentLoader in Visual Studio I was getting the following error
Error:
<pre>
Window title: Microsoft Visual C++ Debug Libary
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

After going on debug in the visual studio I found the following line was responsible

<pre>
xSimpleRegistry->open( OUString( RTL_CONSTASCII_USTRINGPARAM("DocumentLoader.rdb") ), sal_True, sal_False );
</pre>

The DocumentLoader.rdb was missing ... I noticed that if I compiled the DocumentLoader exemples from command line with the makefile provided with the exemple a DocumentLoader.rdb was generated. I had a look at the Makefile I isolated the lines which seemed to generate the DocumentLoader.rdb into my Debug folder (or wherever your set your DocumentLoader.exe to be put by Visual Studio) in my Visual Studio project...

<pre>
regmerge c:\travail\DocumentLoader\debug\DocumentLoader.rdb / "C:\ooo\office\program\types.rdb"

regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c connector.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c remotebridge.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c bridgefac.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c uuresolver.uno.dll
</pre>

I launched all the above lines in the prompt shell and it worked I had my DocumentLoader.rdb in my Debug folder

I launched my exe file and it worked, great...

Now I guess I still need to figure out which *.uno.dll needs to be included for which functions used in the programm, but still it's a good start.
If anyone has any information about that (It may actualy be documented somewhere) don't hesitate)

== The Development Tools of the SDK ==

There are several development tools provided with the SDK : idlc, cppumaker, javamaker, rdbmaker, pkgchk, regcomp, regmerge, regview, xml2cmp, uno, and autodoc. You can find a short documentation on these tools at <OOo_SDK>/docs/tools.html and also in [[Documentation/DevGuide/WritingUNO/Required_Files|Developer's Guide]].

See also [[Compiler_versions_used_by_port_maintainers_and_release_engineers|Compiler versions used by port maintainers and release engineers]]

{{Template:Home_Page}}

= See also =
* [[FR/Documentation/Installation_du_SDK|French version of this chapter]].
* [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno|C++ and UNO tutorial]]
* [http://www.codeproject.com/KB/wtl/Wtl_OOo.aspx Prepare the OOo SDK]
* [http://www.oooforum.org/forum/viewtopic.phtml?t=79911&highlight= missing files in sdk]
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal

[[Category:Tutorial]]
[[Category:Cpp]]
[[Category:Uno]]

SDKInstallation

2014-07-08T02:38:45Z

Global667: /* Installation under Mac OS X */ Make some links internal

{{Documentation/Banner}}
{{Documentation/NeedsRework}}
= How to install the SDK and compile the C++ examples =

For both Linux and Windows the following points are very important if you want to succeed in building C++ components and snippets:
* you need to have OpenOffice.org 1.1.0 or higher installed (SDK won't run without it)
* you need to install the SDK into a directory other than the one of the OOo application

== Installation under Mac OS X ==
{{Documentation/OSX|
The text below describes the installation of the SDK 4.1.0 and OpenOffice 4.1.0 on Mac OS X 10.9.4 with Xcode 4.1.1. It would works for other Intel Mac configurations too.
* Install Xcode. You can get it from the Apple App Store. Perhaps you must be registered as Mac developer under https://developer.apple.com
* Install newest OpenOffice and the corresponding SDK from http://openoffice.apache.org/downloads.html (Choose MacOS_x86-64)
* (Optional) Install MacPorts from http://www.macports.org. You need MacPorts to install optional Unix-like software needed by the SDK.
* Test the SDK. Open a terminal and look for the SDK folder. Now type and run:
<pre>
cd <SDK_Folder>
./setsdkenv_unix # Need to run every time before you use the SDK
cd examples/cpp/DocumentLoader
make
soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager" &
make DocumentLoader.run
</pre>
If everything went fine, you should see a new document, with the content of <SDK_Folder>/examples/cpp/DocumentLoader/test.odt.

Further informations see: http://www.openoffice.org/api/SDK/ and [[Documentation/DevGuide]]

Its recommended to use Eclipse or Netbeans to develop with OpenOffice SDK. There are plugins for booth.
For Eclipse visit [[OpenOffice_Eclipse_Integration]]
For Netbeans visit [[OpenOffice_NetBeans_Integration]]
}}

== Installation under LINUX ==
{{Documentation/Linux|
The text below describe the installation of the SDK 1.1.0 for OpenOffice.org1.1.0

The Software Development Kit (SDK) works on the top of an existing Openoffice.org installation because of using the same libraries. The SDK requires an Openoffice.org installation.
Even if you don't plan to use Java it is strongly recommended to install the JDK (1.4.1_01 or higher for OOo 1.1 SDK)
Of course a C++ compiler is needed (3.0.1 or higher). GNU make (3.79.1 or higher) is also essential.
When ready, launch :
<pre>
tar xzvf Ooo_1.1.0_LinuxIntel_sdk.tar.gz
</pre>

and go to the new created directory (in this example OpenOffice.org1.1_SDK) and launch the configure script which asks you relevant directories. We give here among others :
* where is your OpenOffice.org installed ? (for me /usr/lib/openoffice : noted <Ooo> later)
* Where is your Java SDK installed ? (for me /usr/java/j2sdk1.4.2_04)

Now you are ready to use the SDK. Every time you want to use it you have to launch the setsdkenv_unix script for environment variables. Automating this is not a problem under UNIX.

From now on, we will always note the SDK directory installation as : <OpenOffice.org1.1_SDK>. Please don't confuse with <Ooo> which is the openoffice.org /program/ directory.

You can find a little complement of this chapter in <OpenOffice.org1.1_SDK>/docs/install.html

The OOo2.0SDK installation is done also by launching the setsdkenv_unix script but asking more information :
<pre>
************************************************************************
*
* SDK environment is prepared for Linux
*
* SDK = /home/smoutou/openoffice.org2.0_sdk
* Office = /opt/openoffice.org2.0
* URE =
* Make = /usr/bin
* Zip = /usr/bin
* C++ Compiler = /usr/bin
* Java = /usr/java/j2sdk1.4.2_04
* Special Output directory = /home/smoutou
* Auto deployment = YES
*
************************************************************************
</pre>
If you want to check the Cpp examples, you have to launch first (as mentioned before)
<pre>
./setsdkenv_unix
</pre>
in your shell and then
<pre>
<Ooo>/program/soffice "-accept=socket,host=localhost,port=8100;urp;StarOffice.ServiceManager"
</pre>
For Openoffice.org 2.x, run instead:
<pre>
<Ooo>/program/soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager"
</pre>
Now Openoffice.org is listening on UNO connections through the network (here from localhost only).
We are ready to compile our first example and to check if it works correctly. For that we go in
<OpenOffice.org1.1_SDK>/examples/cpp/DocumentLoader directory.
<pre>
make
</pre>
will compile the example, and
<pre>
make DocumentLoader.run
</pre>
will launch the example. This example only load a Ooowriter's file (test.sxw) provided with the SDK.

Bear in mind the easier way to construct the examples of the SDK is to use the makefiles provided. When you are a beginner with the SDK you always underestimate important steps : for example the registry step discussed later. I estimate to have understand something when I am able to construct it starting with nothing (but skills). In the case of SDK this will take me a long time (and probably will not be finished). Then I can give you an advice : if you want to start a project, begin with modifying an example of the SDK.

Other SDK's examples are discussed later, but you can have a look to :

*[[Counter_Example|Counter example]]

}}

== Installation under Solaris ==
{{Documentation/Linux|
The text below describe the installation of the OpenOffic.org SDK 3.1 for OpenOffice.org3.1

The Software Development Kit (SDK) works on the top of an existing Openoffice.org installation because of using the same libraries. The SDK requires an Openoffice.org installation (default installation directory for Solaris is /opt/openoffice.org/ and /opt/openoffice.org3/)

Depending on which language you wish to use, you will need either:
The Java SDK which can be obtained [http://java.sun.com/javase/downloads/index.jsp here].
Or a C++ complier (g++ 3.0.1 or higher is recommended). As well as GNU make (3.79.1 or higher) is also essential.

First download the Solaris SDK from [http://download.openoffice.org/sdk/index.html here].

Now run the install script by typing the following command. This script will prompt you for a temporary directory where it will extract the installation package. Just press enter and the package will be extracted into the directory shown in brackets (in this case /var/tmp/unpack_openofficeorg). If you wish to extract the package into a separate directory, type in the full directory path at the prompt.

<pre>
# sh OOo-SDK_3.1.1_SolarisSparc_install_en-US.sh
Select the directory in which to save the unpacked files. [/var/tmp/unpack_openofficeorg]

File is being checked for errors ...
Unpacking ...
All files have been successfully unpacked.
</pre>

Now navigate into the packages directory under the unpacked installation directory that was just created.

<pre>
# cd /var/tmp/unpack_openofficeorg/packages
</pre>

Go ahead an install the SDK package using pfexec.

<pre>
# pfexec pkgadd -d .
</pre>

To check if the installation succeeded, attempt to navigate into the sdk directory under the OpenOffic.org basis directory.
<pre>
# cd /opt/openoffice.org/basis3.1/sdk
# ls
bin/ examples/ setsdkenv_unix.csh.in
classes/ idl/ setsdkenv_unix.sh.in
config.guess include/ settings/
config.sub index.html share/
configure.pl lib/
docs/ setsdkenv_unix
</pre>

Now you are ready to use the SDK. Every time you want to use it you have to launch the setsdkenv_unix script for environment variables. Automating this is not a problem under UNIX. You can find a little complement of this chapter in <OpenOffice.org1.1_SDK>/docs/install.html

In order to use the SDK you need to first execute the setsdkevn_unx script in the <OpenOffice.org>/basis3.1/sdk directory (/opt/openoffice.org/basis3.1/sdk for me). Before you execute this script, you need to locate all of the development tools for the language you will be using. Below is a list of the tools that the script prompts for and the locations of the tools on my machine.

<pre>
OpenOffice.org3 installation = /opt/openoffice.org3
GNU make 3.79.1 or higher = /usr/bin
C++ compiler (g++ 3.0.1 or higher) = /usr/bin
Zip = /usr/bin
Java = /usr/jdk/latest/
</pre>

Input the paths to your development tools when prompted.

You are now ready to use the OpenOffice SDK
}}

== Installation under Windows ==
{{Documentation/Windows|

You need a compiler out of the Microsoft Visual Studio family (other compilers like MinGW have turned out to be hard to configure for OOo on Windows).
The first thing after having installed the SDK is to launch the configureWindowsNT.bat and set all the necessary directories for proper use of the SDK.
If that has been done you have already installed everything, but *wait* one very important thing you should still know of:
Every time you want to run your own code or one of the SDK examples you need to launch the setsdkenv_Windows batch file from your command shell. The title of it should now be "Shell prepared for SDK". Happy coding, compiling and building now (I tell you it's easy from now on!).
GanescuCarmen describes some problems he encounter when trying SDK examples under Windows :
“I also use the 1.1 OO version.

I had a lots of problems.
Finally I succeeded to obtain the the header files, and in VC I needed some library to be included into project and some files(uno.idl) to be added to rdb files.
It was very hard to understand what it means registry(the rdb file not the Registry itself).

I was expecting to register something in Registry but it wasn't like this.
And with the service manager I had some problems, with the port, because the connection with 8100 port was not done.
I had to modify a file and to add some code for 8100 port.

But I did it and it works now.”
}}

=== Installing with the free MS Visual C++ Toolkit 2003 ===
{{Documentation/HelpNeeded|This section needs help for update because '''MS Visual C++ Toolkit 2003''' seems no more available. Please have a look at Microsoft for the free Visual C++ tools at the moment.}}
I have installed DevCpp to have a make executable file.
I have downloaded the free Visual C++ Toolkit 2003 here :
http://www.microsoft.com/downloads/details.aspx?FamilyID=272be09d-40bb-49fd-9cb0-4bfa122fa91b&displaylang=en

and then I have installed it. '''(This link is broken.)'''

I launch first C:\openoffice\OpenOffice.org2.0_SDK\configureWindowsNT.bat
which asks any questions :
<pre>
set OO_SDK_HOME=C:\openoffice\OpenOffice.org2.0_SDK
set OFFICE_HOME=C:\Program Files\OpenOffice.org 2.0
set OO_SDK_MAKE_HOME=C:\Dev-C++\Bin
set OO_SDK_CPP_HOME=C:\Program Files\Microsoft Visual C++ Toolkit 2003\Bin
set OO_SDK_JAVA_HOME=C:\Program Files\Java\jdk1.5.0_03
</pre>

and I am ready to launch setsdkenv_windows.bat

I have modified the following file :
C:\openoffice\OpenOffice.org2.0_SDK\examples\DevelopersGuide\ProfUNO\CppBinding\office_connect.cxx
to change the port accordingly to what OOo is listening.

I have modified the makefile :
added :
<pre>
CC_INCLUDES = -I"C:\Program Files\Microsoft Visual C++ Toolkit 2003\include" \
-I"C:\openoffice\OpenOffice.org2.0_SDK\include"
</pre>

and added libraries too :

<pre>
$(OUT_BIN)/%$(EXE_EXT) : $(SAMPLE_OBJ_OUT)/%.$(OBJ_EXT)
-$(MKDIR) $(subst /,$(PS),$(@D))
-$(MKDIR) $(subst /,$(PS),$(SAMPLE_GEN_OUT))
ifeq "$(OS)" "WIN"
$(LINK) $(EXE_LINK_FLAGS) /OUT:$@ /MAP:$(SAMPLE_GEN_OUT)/$(subst $(EXE_EXT),.map,$(@F)) \
$< $(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB)\
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libcp.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libc.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\oldnames.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\kernel32.lib"
else
$(LINK) $(EXE_LINK_FLAGS) $(LINK_LIBS) -o $@ $< \
$(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB) $(STDC++LIB)
endif
</pre>
I suppose there is a more straightforward way to add these libraries with adding the corresponding include path but I am unable to do that with VC++.

I find a solution of the previous problem three weeks later. My problem comes in fact from a bug in setsdkenv_windows.bat. A little correction in the file setsdkenv_windows.bat makes it possible to avoid the makefile modifications :
Put :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "C:\Program Files\Microsoft Visual C++ Toolkit 2003\VCVARS32.bat"
</pre>

instead of :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "%OO_SDK_CPP_HOME%\VCVARS32.bat"
</pre>
I think
<pre>
%OO_SDK_CPP_HOME%\..\VCVARS32.bat
</pre>
could work too (but not checked). You can also move vcvars32.bat in %OO_SDK_CPP_HOME%
("C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin" for me).

=== Other Windows Installations descriptions ===

You can find in [http://www.oooforum.org/forum/viewtopic.phtml?t=23772 OOoForum] a post entitled Guide for develop OpenOffice apps with VC++ .net (by [[CppSDKAuthors|LarsB]])

1.Download and install OpenOffice.

2.Download and install OpenOffice SDK

3.Create a new folder inludecpp in <oo_sdk_path>

4.Open Dos console change directory to <oo_sdk_path>\windows\bin

4.1 run cppumaker with followig paramerers
<pre>
cppumaker -BUCR -O <oo_sdk_path>\includecpp <office_programm_dir>\types.rdb
</pre>
or better with
<pre>
cppumaker -Gc -BUCR -O<includes_path> <ooffice_path>\URE\misc\types.rdb <ooffice_path>\Basis\program\offapi.rdb
</pre>
in recent versions.

(Attention: If you recieve a init error, copy types.rdb into the <oo_sdk_path>\windows\bin folder!)
After that all hpp and hdl files should be created in <oo_sdk_path>\includecpp

5.Open Visual Studio and create a new Win32 Console Application.
Applay the following changes to your project.

5.1. Tools ->Options->Projects->VC++ Directories -> Include Files
Add \include directory and <oo_sdk_path>\includecpp

5.2. Tools ->Options->Projects->VC++ Directories -> Library files
Add <oo_sdk_path>\windows\lib directory

5.3. Tools ->Options->Projects->VC++ Directories -> Executable files
Add <office_programm_dir>\program directory (location where you installed the version of the OpenOffice)

5.4 Open the Project Settings

5.4.1 Change Configuration to all All Configurations (the combobox in the left corner of the window)

5.4.2 Add the additional libraries

Properties->Linker->ComandLine in the Additional Options tab the library files
isal.lib icppu.lib icppuhelper.lib isal.lib isalhelper.lib ireg.lib irmcxt.lib stlport_vc71.lib

6.(example) Add the DocumentLoader.cxx from the cpp examples of the sdk
and compile. The source should compile without errors.

INFO : If you got the following error have a look at the solution 2 postings above!
Up to now, with the steps above i got the following error, when i run the DocumentLoader example.
The error is thrown, when the prog execution reach the following line:

<pre>

Reference< XSimpleRegistry > xSimpleRegistry( ::cppu::createSimpleRegistry() );
</pre>

with error shown below :

<pre>
Error:
Window title: Microsoft Visual C++ Debug Library
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

If somebody has experience with this kind of error it will be nice if he could
post a solution. So that here is a complete little guide for OpenOffice with VC++ .NET

Regards
[[CppSDKAuthors|Lars]]

[[CppSDKAuthors|François]] has improved the complete procedure with remarks :
Following all the steps I (_francois_) encountered two problems

* first in point 4.4.2

But there I guess it's because the procedure was meant for SDK 2 and I'm using SDK 1.1
The stlport_vc71.lib which you must include is distributed with the SDK 2 in the SDK 1.1 stlport_vc7.lib
you just need to include the stlport_vc7.lib instead of stlport_vc71.lib

* second problem after successfuly compiling the DocumentLoader in Visual Studio I was getting the following error
Error:
<pre>
Window title: Microsoft Visual C++ Debug Libary
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

After going on debug in the visual studio I found the following line was responsible

<pre>
xSimpleRegistry->open( OUString( RTL_CONSTASCII_USTRINGPARAM("DocumentLoader.rdb") ), sal_True, sal_False );
</pre>

The DocumentLoader.rdb was missing ... I noticed that if I compiled the DocumentLoader exemples from command line with the makefile provided with the exemple a DocumentLoader.rdb was generated. I had a look at the Makefile I isolated the lines which seemed to generate the DocumentLoader.rdb into my Debug folder (or wherever your set your DocumentLoader.exe to be put by Visual Studio) in my Visual Studio project...

<pre>
regmerge c:\travail\DocumentLoader\debug\DocumentLoader.rdb / "C:\ooo\office\program\types.rdb"

regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c connector.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c remotebridge.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c bridgefac.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c uuresolver.uno.dll
</pre>

I launched all the above lines in the prompt shell and it worked I had my DocumentLoader.rdb in my Debug folder

I launched my exe file and it worked, great...

Now I guess I still need to figure out which *.uno.dll needs to be included for which functions used in the programm, but still it's a good start.
If anyone has any information about that (It may actualy be documented somewhere) don't hesitate)

== The Development Tools of the SDK ==

There are several development tools provided with the SDK : idlc, cppumaker, javamaker, rdbmaker, pkgchk, regcomp, regmerge, regview, xml2cmp, uno, and autodoc. You can find a short documentation on these tools at <OOo_SDK>/docs/tools.html and also in [[Documentation/DevGuide/WritingUNO/Required_Files|Developer's Guide]].

See also [[Compiler_versions_used_by_port_maintainers_and_release_engineers|Compiler versions used by port maintainers and release engineers]]

{{Template:Home_Page}}

= See also =
* [[FR/Documentation/Installation_du_SDK|French version of this chapter]].
* [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno|C++ and UNO tutorial]]
* [http://www.codeproject.com/KB/wtl/Wtl_OOo.aspx Prepare the OOo SDK]
* [http://www.oooforum.org/forum/viewtopic.phtml?t=79911&highlight= missing files in sdk]
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal

[[Category:Tutorial]]
[[Category:Cpp]]
[[Category:Uno]]

SDKInstallation

2014-07-08T02:26:29Z

Global667: /* Installation under Mac OS X */ adding next step links

{{Documentation/Banner}}
{{Documentation/NeedsRework}}
= How to install the SDK and compile the C++ examples =

For both Linux and Windows the following points are very important if you want to succeed in building C++ components and snippets:
* you need to have OpenOffice.org 1.1.0 or higher installed (SDK won't run without it)
* you need to install the SDK into a directory other than the one of the OOo application

== Installation under Mac OS X ==
{{Documentation/OSX|
The text below describes the installation of the SDK 4.1.0 and OpenOffice 4.1.0 on Mac OS X 10.9.4 with Xcode 4.1.1. It would works for other Intel Mac configurations too.
* Install Xcode. You can get it from the Apple App Store. Perhaps you must be registered as Mac developer under https://developer.apple.com
* Install newest OpenOffice and the corresponding SDK from http://openoffice.apache.org/downloads.html (Choose MacOS_x86-64)
* (Optional) Install MacPorts from http://www.macports.org. You need MacPorts to install optional Unix-like software needed by the SDK.
* Test the SDK. Open a terminal and look for the SDK folder. Now type and run:
<pre>
cd <SDK_Folder>
./setsdkenv_unix # Need to run every time before you use the SDK
cd examples/cpp/DocumentLoader
make
soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager" &
make DocumentLoader.run
</pre>
If everything went fine, you should see a new document, with the content of <SDK_Folder>/examples/cpp/DocumentLoader/test.odt.

Further informations see: http://www.openoffice.org/api/SDK/ and https://wiki.openoffice.org/wiki/Documentation/DevGuide

Its recommended to use Eclipse or Netbeans to develop with OpenOffice SDK. There are plugins for booth.
For Eclipse visit https://wiki.openoffice.org/wiki/OpenOffice_Eclipse_Integration
For Netbeans visit https://wiki.openoffice.org/wiki/OpenOffice_NetBeans_Integration
}}

== Installation under LINUX ==
{{Documentation/Linux|
The text below describe the installation of the SDK 1.1.0 for OpenOffice.org1.1.0

The Software Development Kit (SDK) works on the top of an existing Openoffice.org installation because of using the same libraries. The SDK requires an Openoffice.org installation.
Even if you don't plan to use Java it is strongly recommended to install the JDK (1.4.1_01 or higher for OOo 1.1 SDK)
Of course a C++ compiler is needed (3.0.1 or higher). GNU make (3.79.1 or higher) is also essential.
When ready, launch :
<pre>
tar xzvf Ooo_1.1.0_LinuxIntel_sdk.tar.gz
</pre>

and go to the new created directory (in this example OpenOffice.org1.1_SDK) and launch the configure script which asks you relevant directories. We give here among others :
* where is your OpenOffice.org installed ? (for me /usr/lib/openoffice : noted <Ooo> later)
* Where is your Java SDK installed ? (for me /usr/java/j2sdk1.4.2_04)

Now you are ready to use the SDK. Every time you want to use it you have to launch the setsdkenv_unix script for environment variables. Automating this is not a problem under UNIX.

From now on, we will always note the SDK directory installation as : <OpenOffice.org1.1_SDK>. Please don't confuse with <Ooo> which is the openoffice.org /program/ directory.

You can find a little complement of this chapter in <OpenOffice.org1.1_SDK>/docs/install.html

The OOo2.0SDK installation is done also by launching the setsdkenv_unix script but asking more information :
<pre>
************************************************************************
*
* SDK environment is prepared for Linux
*
* SDK = /home/smoutou/openoffice.org2.0_sdk
* Office = /opt/openoffice.org2.0
* URE =
* Make = /usr/bin
* Zip = /usr/bin
* C++ Compiler = /usr/bin
* Java = /usr/java/j2sdk1.4.2_04
* Special Output directory = /home/smoutou
* Auto deployment = YES
*
************************************************************************
</pre>
If you want to check the Cpp examples, you have to launch first (as mentioned before)
<pre>
./setsdkenv_unix
</pre>
in your shell and then
<pre>
<Ooo>/program/soffice "-accept=socket,host=localhost,port=8100;urp;StarOffice.ServiceManager"
</pre>
For Openoffice.org 2.x, run instead:
<pre>
<Ooo>/program/soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager"
</pre>
Now Openoffice.org is listening on UNO connections through the network (here from localhost only).
We are ready to compile our first example and to check if it works correctly. For that we go in
<OpenOffice.org1.1_SDK>/examples/cpp/DocumentLoader directory.
<pre>
make
</pre>
will compile the example, and
<pre>
make DocumentLoader.run
</pre>
will launch the example. This example only load a Ooowriter's file (test.sxw) provided with the SDK.

Bear in mind the easier way to construct the examples of the SDK is to use the makefiles provided. When you are a beginner with the SDK you always underestimate important steps : for example the registry step discussed later. I estimate to have understand something when I am able to construct it starting with nothing (but skills). In the case of SDK this will take me a long time (and probably will not be finished). Then I can give you an advice : if you want to start a project, begin with modifying an example of the SDK.

Other SDK's examples are discussed later, but you can have a look to :

*[[Counter_Example|Counter example]]

}}

== Installation under Solaris ==
{{Documentation/Linux|
The text below describe the installation of the OpenOffic.org SDK 3.1 for OpenOffice.org3.1

The Software Development Kit (SDK) works on the top of an existing Openoffice.org installation because of using the same libraries. The SDK requires an Openoffice.org installation (default installation directory for Solaris is /opt/openoffice.org/ and /opt/openoffice.org3/)

Depending on which language you wish to use, you will need either:
The Java SDK which can be obtained [http://java.sun.com/javase/downloads/index.jsp here].
Or a C++ complier (g++ 3.0.1 or higher is recommended). As well as GNU make (3.79.1 or higher) is also essential.

First download the Solaris SDK from [http://download.openoffice.org/sdk/index.html here].

Now run the install script by typing the following command. This script will prompt you for a temporary directory where it will extract the installation package. Just press enter and the package will be extracted into the directory shown in brackets (in this case /var/tmp/unpack_openofficeorg). If you wish to extract the package into a separate directory, type in the full directory path at the prompt.

<pre>
# sh OOo-SDK_3.1.1_SolarisSparc_install_en-US.sh
Select the directory in which to save the unpacked files. [/var/tmp/unpack_openofficeorg]

File is being checked for errors ...
Unpacking ...
All files have been successfully unpacked.
</pre>

Now navigate into the packages directory under the unpacked installation directory that was just created.

<pre>
# cd /var/tmp/unpack_openofficeorg/packages
</pre>

Go ahead an install the SDK package using pfexec.

<pre>
# pfexec pkgadd -d .
</pre>

To check if the installation succeeded, attempt to navigate into the sdk directory under the OpenOffic.org basis directory.
<pre>
# cd /opt/openoffice.org/basis3.1/sdk
# ls
bin/ examples/ setsdkenv_unix.csh.in
classes/ idl/ setsdkenv_unix.sh.in
config.guess include/ settings/
config.sub index.html share/
configure.pl lib/
docs/ setsdkenv_unix
</pre>

Now you are ready to use the SDK. Every time you want to use it you have to launch the setsdkenv_unix script for environment variables. Automating this is not a problem under UNIX. You can find a little complement of this chapter in <OpenOffice.org1.1_SDK>/docs/install.html

In order to use the SDK you need to first execute the setsdkevn_unx script in the <OpenOffice.org>/basis3.1/sdk directory (/opt/openoffice.org/basis3.1/sdk for me). Before you execute this script, you need to locate all of the development tools for the language you will be using. Below is a list of the tools that the script prompts for and the locations of the tools on my machine.

<pre>
OpenOffice.org3 installation = /opt/openoffice.org3
GNU make 3.79.1 or higher = /usr/bin
C++ compiler (g++ 3.0.1 or higher) = /usr/bin
Zip = /usr/bin
Java = /usr/jdk/latest/
</pre>

Input the paths to your development tools when prompted.

You are now ready to use the OpenOffice SDK
}}

== Installation under Windows ==
{{Documentation/Windows|

You need a compiler out of the Microsoft Visual Studio family (other compilers like MinGW have turned out to be hard to configure for OOo on Windows).
The first thing after having installed the SDK is to launch the configureWindowsNT.bat and set all the necessary directories for proper use of the SDK.
If that has been done you have already installed everything, but *wait* one very important thing you should still know of:
Every time you want to run your own code or one of the SDK examples you need to launch the setsdkenv_Windows batch file from your command shell. The title of it should now be "Shell prepared for SDK". Happy coding, compiling and building now (I tell you it's easy from now on!).
GanescuCarmen describes some problems he encounter when trying SDK examples under Windows :
“I also use the 1.1 OO version.

I had a lots of problems.
Finally I succeeded to obtain the the header files, and in VC I needed some library to be included into project and some files(uno.idl) to be added to rdb files.
It was very hard to understand what it means registry(the rdb file not the Registry itself).

I was expecting to register something in Registry but it wasn't like this.
And with the service manager I had some problems, with the port, because the connection with 8100 port was not done.
I had to modify a file and to add some code for 8100 port.

But I did it and it works now.”
}}

=== Installing with the free MS Visual C++ Toolkit 2003 ===
{{Documentation/HelpNeeded|This section needs help for update because '''MS Visual C++ Toolkit 2003''' seems no more available. Please have a look at Microsoft for the free Visual C++ tools at the moment.}}
I have installed DevCpp to have a make executable file.
I have downloaded the free Visual C++ Toolkit 2003 here :
http://www.microsoft.com/downloads/details.aspx?FamilyID=272be09d-40bb-49fd-9cb0-4bfa122fa91b&displaylang=en

and then I have installed it. '''(This link is broken.)'''

I launch first C:\openoffice\OpenOffice.org2.0_SDK\configureWindowsNT.bat
which asks any questions :
<pre>
set OO_SDK_HOME=C:\openoffice\OpenOffice.org2.0_SDK
set OFFICE_HOME=C:\Program Files\OpenOffice.org 2.0
set OO_SDK_MAKE_HOME=C:\Dev-C++\Bin
set OO_SDK_CPP_HOME=C:\Program Files\Microsoft Visual C++ Toolkit 2003\Bin
set OO_SDK_JAVA_HOME=C:\Program Files\Java\jdk1.5.0_03
</pre>

and I am ready to launch setsdkenv_windows.bat

I have modified the following file :
C:\openoffice\OpenOffice.org2.0_SDK\examples\DevelopersGuide\ProfUNO\CppBinding\office_connect.cxx
to change the port accordingly to what OOo is listening.

I have modified the makefile :
added :
<pre>
CC_INCLUDES = -I"C:\Program Files\Microsoft Visual C++ Toolkit 2003\include" \
-I"C:\openoffice\OpenOffice.org2.0_SDK\include"
</pre>

and added libraries too :

<pre>
$(OUT_BIN)/%$(EXE_EXT) : $(SAMPLE_OBJ_OUT)/%.$(OBJ_EXT)
-$(MKDIR) $(subst /,$(PS),$(@D))
-$(MKDIR) $(subst /,$(PS),$(SAMPLE_GEN_OUT))
ifeq "$(OS)" "WIN"
$(LINK) $(EXE_LINK_FLAGS) /OUT:$@ /MAP:$(SAMPLE_GEN_OUT)/$(subst $(EXE_EXT),.map,$(@F)) \
$< $(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB)\
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libcp.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libc.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\oldnames.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\kernel32.lib"
else
$(LINK) $(EXE_LINK_FLAGS) $(LINK_LIBS) -o $@ $< \
$(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB) $(STDC++LIB)
endif
</pre>
I suppose there is a more straightforward way to add these libraries with adding the corresponding include path but I am unable to do that with VC++.

I find a solution of the previous problem three weeks later. My problem comes in fact from a bug in setsdkenv_windows.bat. A little correction in the file setsdkenv_windows.bat makes it possible to avoid the makefile modifications :
Put :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "C:\Program Files\Microsoft Visual C++ Toolkit 2003\VCVARS32.bat"
</pre>

instead of :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "%OO_SDK_CPP_HOME%\VCVARS32.bat"
</pre>
I think
<pre>
%OO_SDK_CPP_HOME%\..\VCVARS32.bat
</pre>
could work too (but not checked). You can also move vcvars32.bat in %OO_SDK_CPP_HOME%
("C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin" for me).

=== Other Windows Installations descriptions ===

You can find in [http://www.oooforum.org/forum/viewtopic.phtml?t=23772 OOoForum] a post entitled Guide for develop OpenOffice apps with VC++ .net (by [[CppSDKAuthors|LarsB]])

1.Download and install OpenOffice.

2.Download and install OpenOffice SDK

3.Create a new folder inludecpp in <oo_sdk_path>

4.Open Dos console change directory to <oo_sdk_path>\windows\bin

4.1 run cppumaker with followig paramerers
<pre>
cppumaker -BUCR -O <oo_sdk_path>\includecpp <office_programm_dir>\types.rdb
</pre>
or better with
<pre>
cppumaker -Gc -BUCR -O<includes_path> <ooffice_path>\URE\misc\types.rdb <ooffice_path>\Basis\program\offapi.rdb
</pre>
in recent versions.

(Attention: If you recieve a init error, copy types.rdb into the <oo_sdk_path>\windows\bin folder!)
After that all hpp and hdl files should be created in <oo_sdk_path>\includecpp

5.Open Visual Studio and create a new Win32 Console Application.
Applay the following changes to your project.

5.1. Tools ->Options->Projects->VC++ Directories -> Include Files
Add \include directory and <oo_sdk_path>\includecpp

5.2. Tools ->Options->Projects->VC++ Directories -> Library files
Add <oo_sdk_path>\windows\lib directory

5.3. Tools ->Options->Projects->VC++ Directories -> Executable files
Add <office_programm_dir>\program directory (location where you installed the version of the OpenOffice)

5.4 Open the Project Settings

5.4.1 Change Configuration to all All Configurations (the combobox in the left corner of the window)

5.4.2 Add the additional libraries

Properties->Linker->ComandLine in the Additional Options tab the library files
isal.lib icppu.lib icppuhelper.lib isal.lib isalhelper.lib ireg.lib irmcxt.lib stlport_vc71.lib

6.(example) Add the DocumentLoader.cxx from the cpp examples of the sdk
and compile. The source should compile without errors.

INFO : If you got the following error have a look at the solution 2 postings above!
Up to now, with the steps above i got the following error, when i run the DocumentLoader example.
The error is thrown, when the prog execution reach the following line:

<pre>

Reference< XSimpleRegistry > xSimpleRegistry( ::cppu::createSimpleRegistry() );
</pre>

with error shown below :

<pre>
Error:
Window title: Microsoft Visual C++ Debug Library
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

If somebody has experience with this kind of error it will be nice if he could
post a solution. So that here is a complete little guide for OpenOffice with VC++ .NET

Regards
[[CppSDKAuthors|Lars]]

[[CppSDKAuthors|François]] has improved the complete procedure with remarks :
Following all the steps I (_francois_) encountered two problems

* first in point 4.4.2

But there I guess it's because the procedure was meant for SDK 2 and I'm using SDK 1.1
The stlport_vc71.lib which you must include is distributed with the SDK 2 in the SDK 1.1 stlport_vc7.lib
you just need to include the stlport_vc7.lib instead of stlport_vc71.lib

* second problem after successfuly compiling the DocumentLoader in Visual Studio I was getting the following error
Error:
<pre>
Window title: Microsoft Visual C++ Debug Libary
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

After going on debug in the visual studio I found the following line was responsible

<pre>
xSimpleRegistry->open( OUString( RTL_CONSTASCII_USTRINGPARAM("DocumentLoader.rdb") ), sal_True, sal_False );
</pre>

The DocumentLoader.rdb was missing ... I noticed that if I compiled the DocumentLoader exemples from command line with the makefile provided with the exemple a DocumentLoader.rdb was generated. I had a look at the Makefile I isolated the lines which seemed to generate the DocumentLoader.rdb into my Debug folder (or wherever your set your DocumentLoader.exe to be put by Visual Studio) in my Visual Studio project...

<pre>
regmerge c:\travail\DocumentLoader\debug\DocumentLoader.rdb / "C:\ooo\office\program\types.rdb"

regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c connector.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c remotebridge.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c bridgefac.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c uuresolver.uno.dll
</pre>

I launched all the above lines in the prompt shell and it worked I had my DocumentLoader.rdb in my Debug folder

I launched my exe file and it worked, great...

Now I guess I still need to figure out which *.uno.dll needs to be included for which functions used in the programm, but still it's a good start.
If anyone has any information about that (It may actualy be documented somewhere) don't hesitate)

== The Development Tools of the SDK ==

There are several development tools provided with the SDK : idlc, cppumaker, javamaker, rdbmaker, pkgchk, regcomp, regmerge, regview, xml2cmp, uno, and autodoc. You can find a short documentation on these tools at <OOo_SDK>/docs/tools.html and also in [[Documentation/DevGuide/WritingUNO/Required_Files|Developer's Guide]].

See also [[Compiler_versions_used_by_port_maintainers_and_release_engineers|Compiler versions used by port maintainers and release engineers]]

{{Template:Home_Page}}

= See also =
* [[FR/Documentation/Installation_du_SDK|French version of this chapter]].
* [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno|C++ and UNO tutorial]]
* [http://www.codeproject.com/KB/wtl/Wtl_OOo.aspx Prepare the OOo SDK]
* [http://www.oooforum.org/forum/viewtopic.phtml?t=79911&highlight= missing files in sdk]
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal

[[Category:Tutorial]]
[[Category:Cpp]]
[[Category:Uno]]

SDKInstallation

2014-07-08T01:10:34Z

Global667: /* Installation under Mac OS X */ bugfix

{{Documentation/Banner}}
{{Documentation/NeedsRework}}
= How to install the SDK and compile the C++ examples =

For both Linux and Windows the following points are very important if you want to succeed in building C++ components and snippets:
* you need to have OpenOffice.org 1.1.0 or higher installed (SDK won't run without it)
* you need to install the SDK into a directory other than the one of the OOo application

== Installation under Mac OS X ==
{{Documentation/OSX|
The text below describes the installation of the SDK 4.1.0 and OpenOffice 4.1.0 on Mac OS X 10.9.4 with Xcode 4.1.1. It would works for other Intel Mac configurations too.
* Install Xcode. You can get it from the Apple App Store. Perhaps you must be registered as Mac developer under https://developer.apple.com
* Install newest OpenOffice and the corresponding SDK from http://openoffice.apache.org/downloads.html (Choose MacOS_x86-64)
* (Optional) Install MacPorts from http://www.macports.org. You need MacPorts to install optional Unix-like software needed by the SDK.
* Test the SDK. Open a terminal and look for the SDK folder. Now type and run:
<pre>
cd <SDK_Folder>
./setsdkenv_unix # Need to run every time before you use the SDK
cd examples/cpp/DocumentLoader
make
soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager" &
make DocumentLoader.run
</pre>
If everything went fine, you should see a new document, with the content of <SDK_Folder>/examples/cpp/DocumentLoader/test.odt.

Further informations see: http://www.openoffice.org/api/SDK/
}}

== Installation under LINUX ==
{{Documentation/Linux|
The text below describe the installation of the SDK 1.1.0 for OpenOffice.org1.1.0

The Software Development Kit (SDK) works on the top of an existing Openoffice.org installation because of using the same libraries. The SDK requires an Openoffice.org installation.
Even if you don't plan to use Java it is strongly recommended to install the JDK (1.4.1_01 or higher for OOo 1.1 SDK)
Of course a C++ compiler is needed (3.0.1 or higher). GNU make (3.79.1 or higher) is also essential.
When ready, launch :
<pre>
tar xzvf Ooo_1.1.0_LinuxIntel_sdk.tar.gz
</pre>

and go to the new created directory (in this example OpenOffice.org1.1_SDK) and launch the configure script which asks you relevant directories. We give here among others :
* where is your OpenOffice.org installed ? (for me /usr/lib/openoffice : noted <Ooo> later)
* Where is your Java SDK installed ? (for me /usr/java/j2sdk1.4.2_04)

Now you are ready to use the SDK. Every time you want to use it you have to launch the setsdkenv_unix script for environment variables. Automating this is not a problem under UNIX.

From now on, we will always note the SDK directory installation as : <OpenOffice.org1.1_SDK>. Please don't confuse with <Ooo> which is the openoffice.org /program/ directory.

You can find a little complement of this chapter in <OpenOffice.org1.1_SDK>/docs/install.html

The OOo2.0SDK installation is done also by launching the setsdkenv_unix script but asking more information :
<pre>
************************************************************************
*
* SDK environment is prepared for Linux
*
* SDK = /home/smoutou/openoffice.org2.0_sdk
* Office = /opt/openoffice.org2.0
* URE =
* Make = /usr/bin
* Zip = /usr/bin
* C++ Compiler = /usr/bin
* Java = /usr/java/j2sdk1.4.2_04
* Special Output directory = /home/smoutou
* Auto deployment = YES
*
************************************************************************
</pre>
If you want to check the Cpp examples, you have to launch first (as mentioned before)
<pre>
./setsdkenv_unix
</pre>
in your shell and then
<pre>
<Ooo>/program/soffice "-accept=socket,host=localhost,port=8100;urp;StarOffice.ServiceManager"
</pre>
For Openoffice.org 2.x, run instead:
<pre>
<Ooo>/program/soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager"
</pre>
Now Openoffice.org is listening on UNO connections through the network (here from localhost only).
We are ready to compile our first example and to check if it works correctly. For that we go in
<OpenOffice.org1.1_SDK>/examples/cpp/DocumentLoader directory.
<pre>
make
</pre>
will compile the example, and
<pre>
make DocumentLoader.run
</pre>
will launch the example. This example only load a Ooowriter's file (test.sxw) provided with the SDK.

Bear in mind the easier way to construct the examples of the SDK is to use the makefiles provided. When you are a beginner with the SDK you always underestimate important steps : for example the registry step discussed later. I estimate to have understand something when I am able to construct it starting with nothing (but skills). In the case of SDK this will take me a long time (and probably will not be finished). Then I can give you an advice : if you want to start a project, begin with modifying an example of the SDK.

Other SDK's examples are discussed later, but you can have a look to :

*[[Counter_Example|Counter example]]

}}

== Installation under Solaris ==
{{Documentation/Linux|
The text below describe the installation of the OpenOffic.org SDK 3.1 for OpenOffice.org3.1

The Software Development Kit (SDK) works on the top of an existing Openoffice.org installation because of using the same libraries. The SDK requires an Openoffice.org installation (default installation directory for Solaris is /opt/openoffice.org/ and /opt/openoffice.org3/)

Depending on which language you wish to use, you will need either:
The Java SDK which can be obtained [http://java.sun.com/javase/downloads/index.jsp here].
Or a C++ complier (g++ 3.0.1 or higher is recommended). As well as GNU make (3.79.1 or higher) is also essential.

First download the Solaris SDK from [http://download.openoffice.org/sdk/index.html here].

Now run the install script by typing the following command. This script will prompt you for a temporary directory where it will extract the installation package. Just press enter and the package will be extracted into the directory shown in brackets (in this case /var/tmp/unpack_openofficeorg). If you wish to extract the package into a separate directory, type in the full directory path at the prompt.

<pre>
# sh OOo-SDK_3.1.1_SolarisSparc_install_en-US.sh
Select the directory in which to save the unpacked files. [/var/tmp/unpack_openofficeorg]

File is being checked for errors ...
Unpacking ...
All files have been successfully unpacked.
</pre>

Now navigate into the packages directory under the unpacked installation directory that was just created.

<pre>
# cd /var/tmp/unpack_openofficeorg/packages
</pre>

Go ahead an install the SDK package using pfexec.

<pre>
# pfexec pkgadd -d .
</pre>

To check if the installation succeeded, attempt to navigate into the sdk directory under the OpenOffic.org basis directory.
<pre>
# cd /opt/openoffice.org/basis3.1/sdk
# ls
bin/ examples/ setsdkenv_unix.csh.in
classes/ idl/ setsdkenv_unix.sh.in
config.guess include/ settings/
config.sub index.html share/
configure.pl lib/
docs/ setsdkenv_unix
</pre>

Now you are ready to use the SDK. Every time you want to use it you have to launch the setsdkenv_unix script for environment variables. Automating this is not a problem under UNIX. You can find a little complement of this chapter in <OpenOffice.org1.1_SDK>/docs/install.html

In order to use the SDK you need to first execute the setsdkevn_unx script in the <OpenOffice.org>/basis3.1/sdk directory (/opt/openoffice.org/basis3.1/sdk for me). Before you execute this script, you need to locate all of the development tools for the language you will be using. Below is a list of the tools that the script prompts for and the locations of the tools on my machine.

<pre>
OpenOffice.org3 installation = /opt/openoffice.org3
GNU make 3.79.1 or higher = /usr/bin
C++ compiler (g++ 3.0.1 or higher) = /usr/bin
Zip = /usr/bin
Java = /usr/jdk/latest/
</pre>

Input the paths to your development tools when prompted.

You are now ready to use the OpenOffice SDK
}}

== Installation under Windows ==
{{Documentation/Windows|

You need a compiler out of the Microsoft Visual Studio family (other compilers like MinGW have turned out to be hard to configure for OOo on Windows).
The first thing after having installed the SDK is to launch the configureWindowsNT.bat and set all the necessary directories for proper use of the SDK.
If that has been done you have already installed everything, but *wait* one very important thing you should still know of:
Every time you want to run your own code or one of the SDK examples you need to launch the setsdkenv_Windows batch file from your command shell. The title of it should now be "Shell prepared for SDK". Happy coding, compiling and building now (I tell you it's easy from now on!).
GanescuCarmen describes some problems he encounter when trying SDK examples under Windows :
“I also use the 1.1 OO version.

I had a lots of problems.
Finally I succeeded to obtain the the header files, and in VC I needed some library to be included into project and some files(uno.idl) to be added to rdb files.
It was very hard to understand what it means registry(the rdb file not the Registry itself).

I was expecting to register something in Registry but it wasn't like this.
And with the service manager I had some problems, with the port, because the connection with 8100 port was not done.
I had to modify a file and to add some code for 8100 port.

But I did it and it works now.”
}}

=== Installing with the free MS Visual C++ Toolkit 2003 ===
{{Documentation/HelpNeeded|This section needs help for update because '''MS Visual C++ Toolkit 2003''' seems no more available. Please have a look at Microsoft for the free Visual C++ tools at the moment.}}
I have installed DevCpp to have a make executable file.
I have downloaded the free Visual C++ Toolkit 2003 here :
http://www.microsoft.com/downloads/details.aspx?FamilyID=272be09d-40bb-49fd-9cb0-4bfa122fa91b&displaylang=en

and then I have installed it. '''(This link is broken.)'''

I launch first C:\openoffice\OpenOffice.org2.0_SDK\configureWindowsNT.bat
which asks any questions :
<pre>
set OO_SDK_HOME=C:\openoffice\OpenOffice.org2.0_SDK
set OFFICE_HOME=C:\Program Files\OpenOffice.org 2.0
set OO_SDK_MAKE_HOME=C:\Dev-C++\Bin
set OO_SDK_CPP_HOME=C:\Program Files\Microsoft Visual C++ Toolkit 2003\Bin
set OO_SDK_JAVA_HOME=C:\Program Files\Java\jdk1.5.0_03
</pre>

and I am ready to launch setsdkenv_windows.bat

I have modified the following file :
C:\openoffice\OpenOffice.org2.0_SDK\examples\DevelopersGuide\ProfUNO\CppBinding\office_connect.cxx
to change the port accordingly to what OOo is listening.

I have modified the makefile :
added :
<pre>
CC_INCLUDES = -I"C:\Program Files\Microsoft Visual C++ Toolkit 2003\include" \
-I"C:\openoffice\OpenOffice.org2.0_SDK\include"
</pre>

and added libraries too :

<pre>
$(OUT_BIN)/%$(EXE_EXT) : $(SAMPLE_OBJ_OUT)/%.$(OBJ_EXT)
-$(MKDIR) $(subst /,$(PS),$(@D))
-$(MKDIR) $(subst /,$(PS),$(SAMPLE_GEN_OUT))
ifeq "$(OS)" "WIN"
$(LINK) $(EXE_LINK_FLAGS) /OUT:$@ /MAP:$(SAMPLE_GEN_OUT)/$(subst $(EXE_EXT),.map,$(@F)) \
$< $(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB)\
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libcp.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libc.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\oldnames.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\kernel32.lib"
else
$(LINK) $(EXE_LINK_FLAGS) $(LINK_LIBS) -o $@ $< \
$(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB) $(STDC++LIB)
endif
</pre>
I suppose there is a more straightforward way to add these libraries with adding the corresponding include path but I am unable to do that with VC++.

I find a solution of the previous problem three weeks later. My problem comes in fact from a bug in setsdkenv_windows.bat. A little correction in the file setsdkenv_windows.bat makes it possible to avoid the makefile modifications :
Put :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "C:\Program Files\Microsoft Visual C++ Toolkit 2003\VCVARS32.bat"
</pre>

instead of :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "%OO_SDK_CPP_HOME%\VCVARS32.bat"
</pre>
I think
<pre>
%OO_SDK_CPP_HOME%\..\VCVARS32.bat
</pre>
could work too (but not checked). You can also move vcvars32.bat in %OO_SDK_CPP_HOME%
("C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin" for me).

=== Other Windows Installations descriptions ===

You can find in [http://www.oooforum.org/forum/viewtopic.phtml?t=23772 OOoForum] a post entitled Guide for develop OpenOffice apps with VC++ .net (by [[CppSDKAuthors|LarsB]])

1.Download and install OpenOffice.

2.Download and install OpenOffice SDK

3.Create a new folder inludecpp in <oo_sdk_path>

4.Open Dos console change directory to <oo_sdk_path>\windows\bin

4.1 run cppumaker with followig paramerers
<pre>
cppumaker -BUCR -O <oo_sdk_path>\includecpp <office_programm_dir>\types.rdb
</pre>
or better with
<pre>
cppumaker -Gc -BUCR -O<includes_path> <ooffice_path>\URE\misc\types.rdb <ooffice_path>\Basis\program\offapi.rdb
</pre>
in recent versions.

(Attention: If you recieve a init error, copy types.rdb into the <oo_sdk_path>\windows\bin folder!)
After that all hpp and hdl files should be created in <oo_sdk_path>\includecpp

5.Open Visual Studio and create a new Win32 Console Application.
Applay the following changes to your project.

5.1. Tools ->Options->Projects->VC++ Directories -> Include Files
Add \include directory and <oo_sdk_path>\includecpp

5.2. Tools ->Options->Projects->VC++ Directories -> Library files
Add <oo_sdk_path>\windows\lib directory

5.3. Tools ->Options->Projects->VC++ Directories -> Executable files
Add <office_programm_dir>\program directory (location where you installed the version of the OpenOffice)

5.4 Open the Project Settings

5.4.1 Change Configuration to all All Configurations (the combobox in the left corner of the window)

5.4.2 Add the additional libraries

Properties->Linker->ComandLine in the Additional Options tab the library files
isal.lib icppu.lib icppuhelper.lib isal.lib isalhelper.lib ireg.lib irmcxt.lib stlport_vc71.lib

6.(example) Add the DocumentLoader.cxx from the cpp examples of the sdk
and compile. The source should compile without errors.

INFO : If you got the following error have a look at the solution 2 postings above!
Up to now, with the steps above i got the following error, when i run the DocumentLoader example.
The error is thrown, when the prog execution reach the following line:

<pre>

Reference< XSimpleRegistry > xSimpleRegistry( ::cppu::createSimpleRegistry() );
</pre>

with error shown below :

<pre>
Error:
Window title: Microsoft Visual C++ Debug Library
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

If somebody has experience with this kind of error it will be nice if he could
post a solution. So that here is a complete little guide for OpenOffice with VC++ .NET

Regards
[[CppSDKAuthors|Lars]]

[[CppSDKAuthors|François]] has improved the complete procedure with remarks :
Following all the steps I (_francois_) encountered two problems

* first in point 4.4.2

But there I guess it's because the procedure was meant for SDK 2 and I'm using SDK 1.1
The stlport_vc71.lib which you must include is distributed with the SDK 2 in the SDK 1.1 stlport_vc7.lib
you just need to include the stlport_vc7.lib instead of stlport_vc71.lib

* second problem after successfuly compiling the DocumentLoader in Visual Studio I was getting the following error
Error:
<pre>
Window title: Microsoft Visual C++ Debug Libary
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

After going on debug in the visual studio I found the following line was responsible

<pre>
xSimpleRegistry->open( OUString( RTL_CONSTASCII_USTRINGPARAM("DocumentLoader.rdb") ), sal_True, sal_False );
</pre>

The DocumentLoader.rdb was missing ... I noticed that if I compiled the DocumentLoader exemples from command line with the makefile provided with the exemple a DocumentLoader.rdb was generated. I had a look at the Makefile I isolated the lines which seemed to generate the DocumentLoader.rdb into my Debug folder (or wherever your set your DocumentLoader.exe to be put by Visual Studio) in my Visual Studio project...

<pre>
regmerge c:\travail\DocumentLoader\debug\DocumentLoader.rdb / "C:\ooo\office\program\types.rdb"

regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c connector.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c remotebridge.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c bridgefac.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c uuresolver.uno.dll
</pre>

I launched all the above lines in the prompt shell and it worked I had my DocumentLoader.rdb in my Debug folder

I launched my exe file and it worked, great...

Now I guess I still need to figure out which *.uno.dll needs to be included for which functions used in the programm, but still it's a good start.
If anyone has any information about that (It may actualy be documented somewhere) don't hesitate)

== The Development Tools of the SDK ==

There are several development tools provided with the SDK : idlc, cppumaker, javamaker, rdbmaker, pkgchk, regcomp, regmerge, regview, xml2cmp, uno, and autodoc. You can find a short documentation on these tools at <OOo_SDK>/docs/tools.html and also in [[Documentation/DevGuide/WritingUNO/Required_Files|Developer's Guide]].

See also [[Compiler_versions_used_by_port_maintainers_and_release_engineers|Compiler versions used by port maintainers and release engineers]]

{{Template:Home_Page}}

= See also =
* [[FR/Documentation/Installation_du_SDK|French version of this chapter]].
* [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno|C++ and UNO tutorial]]
* [http://www.codeproject.com/KB/wtl/Wtl_OOo.aspx Prepare the OOo SDK]
* [http://www.oooforum.org/forum/viewtopic.phtml?t=79911&highlight= missing files in sdk]
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal

[[Category:Tutorial]]
[[Category:Cpp]]
[[Category:Uno]]

SDKInstallation

2014-07-08T00:59:57Z

Global667: /* Installation under Mac OS X */ bugfix

{{Documentation/Banner}}
{{Documentation/NeedsRework}}
= How to install the SDK and compile the C++ examples =

For both Linux and Windows the following points are very important if you want to succeed in building C++ components and snippets:
* you need to have OpenOffice.org 1.1.0 or higher installed (SDK won't run without it)
* you need to install the SDK into a directory other than the one of the OOo application

== Installation under Mac OS X ==
{{Documentation/OSX|
The text below describes the installation of the SDK 4.1.0 and OpenOffice 4.1.0 on Mac OS X 10.9.4 with Xcode 4.1.1. It would works for other Intel Mac configurations too.
* Install Xcode. You can get it from the Apple App Store. Perhaps you must be registered as Mac developer under https://developer.apple.com
* Install newest OpenOffice and the corresponding SDK from http://openoffice.apache.org/downloads.html (Choose MacOS_x86-64)
* (Optional) Install MacPorts from http://www.macports.org. You need MacPorts to install optional Unix-like software needed by the SDK.
* Test the SDK. Open a terminal and look for the SDK folder. Now type and run:
<pre>
cd <SDK_Folder>
./setsdkenv_unix
cd examples/cpp/DocumentLoader
make
soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager" & make DocumentLoader.run
</pre>
If everything went fine, you should see a new document, with the content of <SDK_Folder>/examples/cpp/DocumentLoader/test.odt.

Further informations see: http://www.openoffice.org/api/SDK/
}}

== Installation under LINUX ==
{{Documentation/Linux|
The text below describe the installation of the SDK 1.1.0 for OpenOffice.org1.1.0

The Software Development Kit (SDK) works on the top of an existing Openoffice.org installation because of using the same libraries. The SDK requires an Openoffice.org installation.
Even if you don't plan to use Java it is strongly recommended to install the JDK (1.4.1_01 or higher for OOo 1.1 SDK)
Of course a C++ compiler is needed (3.0.1 or higher). GNU make (3.79.1 or higher) is also essential.
When ready, launch :
<pre>
tar xzvf Ooo_1.1.0_LinuxIntel_sdk.tar.gz
</pre>

and go to the new created directory (in this example OpenOffice.org1.1_SDK) and launch the configure script which asks you relevant directories. We give here among others :
* where is your OpenOffice.org installed ? (for me /usr/lib/openoffice : noted <Ooo> later)
* Where is your Java SDK installed ? (for me /usr/java/j2sdk1.4.2_04)

Now you are ready to use the SDK. Every time you want to use it you have to launch the setsdkenv_unix script for environment variables. Automating this is not a problem under UNIX.

From now on, we will always note the SDK directory installation as : <OpenOffice.org1.1_SDK>. Please don't confuse with <Ooo> which is the openoffice.org /program/ directory.

You can find a little complement of this chapter in <OpenOffice.org1.1_SDK>/docs/install.html

The OOo2.0SDK installation is done also by launching the setsdkenv_unix script but asking more information :
<pre>
************************************************************************
*
* SDK environment is prepared for Linux
*
* SDK = /home/smoutou/openoffice.org2.0_sdk
* Office = /opt/openoffice.org2.0
* URE =
* Make = /usr/bin
* Zip = /usr/bin
* C++ Compiler = /usr/bin
* Java = /usr/java/j2sdk1.4.2_04
* Special Output directory = /home/smoutou
* Auto deployment = YES
*
************************************************************************
</pre>
If you want to check the Cpp examples, you have to launch first (as mentioned before)
<pre>
./setsdkenv_unix
</pre>
in your shell and then
<pre>
<Ooo>/program/soffice "-accept=socket,host=localhost,port=8100;urp;StarOffice.ServiceManager"
</pre>
For Openoffice.org 2.x, run instead:
<pre>
<Ooo>/program/soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager"
</pre>
Now Openoffice.org is listening on UNO connections through the network (here from localhost only).
We are ready to compile our first example and to check if it works correctly. For that we go in
<OpenOffice.org1.1_SDK>/examples/cpp/DocumentLoader directory.
<pre>
make
</pre>
will compile the example, and
<pre>
make DocumentLoader.run
</pre>
will launch the example. This example only load a Ooowriter's file (test.sxw) provided with the SDK.

Bear in mind the easier way to construct the examples of the SDK is to use the makefiles provided. When you are a beginner with the SDK you always underestimate important steps : for example the registry step discussed later. I estimate to have understand something when I am able to construct it starting with nothing (but skills). In the case of SDK this will take me a long time (and probably will not be finished). Then I can give you an advice : if you want to start a project, begin with modifying an example of the SDK.

Other SDK's examples are discussed later, but you can have a look to :

*[[Counter_Example|Counter example]]

}}

== Installation under Solaris ==
{{Documentation/Linux|
The text below describe the installation of the OpenOffic.org SDK 3.1 for OpenOffice.org3.1

The Software Development Kit (SDK) works on the top of an existing Openoffice.org installation because of using the same libraries. The SDK requires an Openoffice.org installation (default installation directory for Solaris is /opt/openoffice.org/ and /opt/openoffice.org3/)

Depending on which language you wish to use, you will need either:
The Java SDK which can be obtained [http://java.sun.com/javase/downloads/index.jsp here].
Or a C++ complier (g++ 3.0.1 or higher is recommended). As well as GNU make (3.79.1 or higher) is also essential.

First download the Solaris SDK from [http://download.openoffice.org/sdk/index.html here].

Now run the install script by typing the following command. This script will prompt you for a temporary directory where it will extract the installation package. Just press enter and the package will be extracted into the directory shown in brackets (in this case /var/tmp/unpack_openofficeorg). If you wish to extract the package into a separate directory, type in the full directory path at the prompt.

<pre>
# sh OOo-SDK_3.1.1_SolarisSparc_install_en-US.sh
Select the directory in which to save the unpacked files. [/var/tmp/unpack_openofficeorg]

File is being checked for errors ...
Unpacking ...
All files have been successfully unpacked.
</pre>

Now navigate into the packages directory under the unpacked installation directory that was just created.

<pre>
# cd /var/tmp/unpack_openofficeorg/packages
</pre>

Go ahead an install the SDK package using pfexec.

<pre>
# pfexec pkgadd -d .
</pre>

To check if the installation succeeded, attempt to navigate into the sdk directory under the OpenOffic.org basis directory.
<pre>
# cd /opt/openoffice.org/basis3.1/sdk
# ls
bin/ examples/ setsdkenv_unix.csh.in
classes/ idl/ setsdkenv_unix.sh.in
config.guess include/ settings/
config.sub index.html share/
configure.pl lib/
docs/ setsdkenv_unix
</pre>

Now you are ready to use the SDK. Every time you want to use it you have to launch the setsdkenv_unix script for environment variables. Automating this is not a problem under UNIX. You can find a little complement of this chapter in <OpenOffice.org1.1_SDK>/docs/install.html

In order to use the SDK you need to first execute the setsdkevn_unx script in the <OpenOffice.org>/basis3.1/sdk directory (/opt/openoffice.org/basis3.1/sdk for me). Before you execute this script, you need to locate all of the development tools for the language you will be using. Below is a list of the tools that the script prompts for and the locations of the tools on my machine.

<pre>
OpenOffice.org3 installation = /opt/openoffice.org3
GNU make 3.79.1 or higher = /usr/bin
C++ compiler (g++ 3.0.1 or higher) = /usr/bin
Zip = /usr/bin
Java = /usr/jdk/latest/
</pre>

Input the paths to your development tools when prompted.

You are now ready to use the OpenOffice SDK
}}

== Installation under Windows ==
{{Documentation/Windows|

You need a compiler out of the Microsoft Visual Studio family (other compilers like MinGW have turned out to be hard to configure for OOo on Windows).
The first thing after having installed the SDK is to launch the configureWindowsNT.bat and set all the necessary directories for proper use of the SDK.
If that has been done you have already installed everything, but *wait* one very important thing you should still know of:
Every time you want to run your own code or one of the SDK examples you need to launch the setsdkenv_Windows batch file from your command shell. The title of it should now be "Shell prepared for SDK". Happy coding, compiling and building now (I tell you it's easy from now on!).
GanescuCarmen describes some problems he encounter when trying SDK examples under Windows :
“I also use the 1.1 OO version.

I had a lots of problems.
Finally I succeeded to obtain the the header files, and in VC I needed some library to be included into project and some files(uno.idl) to be added to rdb files.
It was very hard to understand what it means registry(the rdb file not the Registry itself).

I was expecting to register something in Registry but it wasn't like this.
And with the service manager I had some problems, with the port, because the connection with 8100 port was not done.
I had to modify a file and to add some code for 8100 port.

But I did it and it works now.”
}}

=== Installing with the free MS Visual C++ Toolkit 2003 ===
{{Documentation/HelpNeeded|This section needs help for update because '''MS Visual C++ Toolkit 2003''' seems no more available. Please have a look at Microsoft for the free Visual C++ tools at the moment.}}
I have installed DevCpp to have a make executable file.
I have downloaded the free Visual C++ Toolkit 2003 here :
http://www.microsoft.com/downloads/details.aspx?FamilyID=272be09d-40bb-49fd-9cb0-4bfa122fa91b&displaylang=en

and then I have installed it. '''(This link is broken.)'''

I launch first C:\openoffice\OpenOffice.org2.0_SDK\configureWindowsNT.bat
which asks any questions :
<pre>
set OO_SDK_HOME=C:\openoffice\OpenOffice.org2.0_SDK
set OFFICE_HOME=C:\Program Files\OpenOffice.org 2.0
set OO_SDK_MAKE_HOME=C:\Dev-C++\Bin
set OO_SDK_CPP_HOME=C:\Program Files\Microsoft Visual C++ Toolkit 2003\Bin
set OO_SDK_JAVA_HOME=C:\Program Files\Java\jdk1.5.0_03
</pre>

and I am ready to launch setsdkenv_windows.bat

I have modified the following file :
C:\openoffice\OpenOffice.org2.0_SDK\examples\DevelopersGuide\ProfUNO\CppBinding\office_connect.cxx
to change the port accordingly to what OOo is listening.

I have modified the makefile :
added :
<pre>
CC_INCLUDES = -I"C:\Program Files\Microsoft Visual C++ Toolkit 2003\include" \
-I"C:\openoffice\OpenOffice.org2.0_SDK\include"
</pre>

and added libraries too :

<pre>
$(OUT_BIN)/%$(EXE_EXT) : $(SAMPLE_OBJ_OUT)/%.$(OBJ_EXT)
-$(MKDIR) $(subst /,$(PS),$(@D))
-$(MKDIR) $(subst /,$(PS),$(SAMPLE_GEN_OUT))
ifeq "$(OS)" "WIN"
$(LINK) $(EXE_LINK_FLAGS) /OUT:$@ /MAP:$(SAMPLE_GEN_OUT)/$(subst $(EXE_EXT),.map,$(@F)) \
$< $(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB)\
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libcp.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libc.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\oldnames.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\kernel32.lib"
else
$(LINK) $(EXE_LINK_FLAGS) $(LINK_LIBS) -o $@ $< \
$(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB) $(STDC++LIB)
endif
</pre>
I suppose there is a more straightforward way to add these libraries with adding the corresponding include path but I am unable to do that with VC++.

I find a solution of the previous problem three weeks later. My problem comes in fact from a bug in setsdkenv_windows.bat. A little correction in the file setsdkenv_windows.bat makes it possible to avoid the makefile modifications :
Put :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "C:\Program Files\Microsoft Visual C++ Toolkit 2003\VCVARS32.bat"
</pre>

instead of :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "%OO_SDK_CPP_HOME%\VCVARS32.bat"
</pre>
I think
<pre>
%OO_SDK_CPP_HOME%\..\VCVARS32.bat
</pre>
could work too (but not checked). You can also move vcvars32.bat in %OO_SDK_CPP_HOME%
("C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin" for me).

=== Other Windows Installations descriptions ===

You can find in [http://www.oooforum.org/forum/viewtopic.phtml?t=23772 OOoForum] a post entitled Guide for develop OpenOffice apps with VC++ .net (by [[CppSDKAuthors|LarsB]])

1.Download and install OpenOffice.

2.Download and install OpenOffice SDK

3.Create a new folder inludecpp in <oo_sdk_path>

4.Open Dos console change directory to <oo_sdk_path>\windows\bin

4.1 run cppumaker with followig paramerers
<pre>
cppumaker -BUCR -O <oo_sdk_path>\includecpp <office_programm_dir>\types.rdb
</pre>
or better with
<pre>
cppumaker -Gc -BUCR -O<includes_path> <ooffice_path>\URE\misc\types.rdb <ooffice_path>\Basis\program\offapi.rdb
</pre>
in recent versions.

(Attention: If you recieve a init error, copy types.rdb into the <oo_sdk_path>\windows\bin folder!)
After that all hpp and hdl files should be created in <oo_sdk_path>\includecpp

5.Open Visual Studio and create a new Win32 Console Application.
Applay the following changes to your project.

5.1. Tools ->Options->Projects->VC++ Directories -> Include Files
Add \include directory and <oo_sdk_path>\includecpp

5.2. Tools ->Options->Projects->VC++ Directories -> Library files
Add <oo_sdk_path>\windows\lib directory

5.3. Tools ->Options->Projects->VC++ Directories -> Executable files
Add <office_programm_dir>\program directory (location where you installed the version of the OpenOffice)

5.4 Open the Project Settings

5.4.1 Change Configuration to all All Configurations (the combobox in the left corner of the window)

5.4.2 Add the additional libraries

Properties->Linker->ComandLine in the Additional Options tab the library files
isal.lib icppu.lib icppuhelper.lib isal.lib isalhelper.lib ireg.lib irmcxt.lib stlport_vc71.lib

6.(example) Add the DocumentLoader.cxx from the cpp examples of the sdk
and compile. The source should compile without errors.

INFO : If you got the following error have a look at the solution 2 postings above!
Up to now, with the steps above i got the following error, when i run the DocumentLoader example.
The error is thrown, when the prog execution reach the following line:

<pre>

Reference< XSimpleRegistry > xSimpleRegistry( ::cppu::createSimpleRegistry() );
</pre>

with error shown below :

<pre>
Error:
Window title: Microsoft Visual C++ Debug Library
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

If somebody has experience with this kind of error it will be nice if he could
post a solution. So that here is a complete little guide for OpenOffice with VC++ .NET

Regards
[[CppSDKAuthors|Lars]]

[[CppSDKAuthors|François]] has improved the complete procedure with remarks :
Following all the steps I (_francois_) encountered two problems

* first in point 4.4.2

But there I guess it's because the procedure was meant for SDK 2 and I'm using SDK 1.1
The stlport_vc71.lib which you must include is distributed with the SDK 2 in the SDK 1.1 stlport_vc7.lib
you just need to include the stlport_vc7.lib instead of stlport_vc71.lib

* second problem after successfuly compiling the DocumentLoader in Visual Studio I was getting the following error
Error:
<pre>
Window title: Microsoft Visual C++ Debug Libary
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

After going on debug in the visual studio I found the following line was responsible

<pre>
xSimpleRegistry->open( OUString( RTL_CONSTASCII_USTRINGPARAM("DocumentLoader.rdb") ), sal_True, sal_False );
</pre>

The DocumentLoader.rdb was missing ... I noticed that if I compiled the DocumentLoader exemples from command line with the makefile provided with the exemple a DocumentLoader.rdb was generated. I had a look at the Makefile I isolated the lines which seemed to generate the DocumentLoader.rdb into my Debug folder (or wherever your set your DocumentLoader.exe to be put by Visual Studio) in my Visual Studio project...

<pre>
regmerge c:\travail\DocumentLoader\debug\DocumentLoader.rdb / "C:\ooo\office\program\types.rdb"

regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c connector.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c remotebridge.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c bridgefac.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c uuresolver.uno.dll
</pre>

I launched all the above lines in the prompt shell and it worked I had my DocumentLoader.rdb in my Debug folder

I launched my exe file and it worked, great...

Now I guess I still need to figure out which *.uno.dll needs to be included for which functions used in the programm, but still it's a good start.
If anyone has any information about that (It may actualy be documented somewhere) don't hesitate)

== The Development Tools of the SDK ==

There are several development tools provided with the SDK : idlc, cppumaker, javamaker, rdbmaker, pkgchk, regcomp, regmerge, regview, xml2cmp, uno, and autodoc. You can find a short documentation on these tools at <OOo_SDK>/docs/tools.html and also in [[Documentation/DevGuide/WritingUNO/Required_Files|Developer's Guide]].

See also [[Compiler_versions_used_by_port_maintainers_and_release_engineers|Compiler versions used by port maintainers and release engineers]]

{{Template:Home_Page}}

= See also =
* [[FR/Documentation/Installation_du_SDK|French version of this chapter]].
* [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno|C++ and UNO tutorial]]
* [http://www.codeproject.com/KB/wtl/Wtl_OOo.aspx Prepare the OOo SDK]
* [http://www.oooforum.org/forum/viewtopic.phtml?t=79911&highlight= missing files in sdk]
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal

[[Category:Tutorial]]
[[Category:Cpp]]
[[Category:Uno]]

SDKInstallation

2014-07-08T00:55:19Z

Global667: Put windows stuff in windows chapter

{{Documentation/Banner}}
{{Documentation/NeedsRework}}
= How to install the SDK and compile the C++ examples =

For both Linux and Windows the following points are very important if you want to succeed in building C++ components and snippets:
* you need to have OpenOffice.org 1.1.0 or higher installed (SDK won't run without it)
* you need to install the SDK into a directory other than the one of the OOo application

== Installation under Mac OS X ==
{{Documentation/OSX|
The text below describes the installation of the SDK 4.1.0 and OpenOffice 4.1.0 on Mac OS X 10.9.4 with Xcode 4.1.1. It would works for other Intel Mac configurations too.
* Install Xcode. You can get it from the Apple App Store. Perhaps you must be registered as Mac developer under https://developer.apple.com
* Install newest OpenOffice and the corresponding SDK from http://openoffice.apache.org/downloads.html (Choose MacOS_x86-64)
* Install MacPorts from http://www.macports.org. Perhaps you need to customize the path. You need MacPorts to install Unix-like software needed by the SDK.
* Test the SDK. Open a terminal and look for the SDK folder. Now type and run:
<pre>
cd <SDK_Folder>
./setsdkenv_unix
cd examples/cpp/DocumentLoader
make
soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager" & make DocumentLoader.run
</pre>
If everything went fine, you should see a new document, with the content of <SDK_Folder>/examples/cpp/DocumentLoader/test.odt.

Further informations see: http://www.openoffice.org/api/SDK/
}}

== Installation under LINUX ==
{{Documentation/Linux|
The text below describe the installation of the SDK 1.1.0 for OpenOffice.org1.1.0

The Software Development Kit (SDK) works on the top of an existing Openoffice.org installation because of using the same libraries. The SDK requires an Openoffice.org installation.
Even if you don't plan to use Java it is strongly recommended to install the JDK (1.4.1_01 or higher for OOo 1.1 SDK)
Of course a C++ compiler is needed (3.0.1 or higher). GNU make (3.79.1 or higher) is also essential.
When ready, launch :
<pre>
tar xzvf Ooo_1.1.0_LinuxIntel_sdk.tar.gz
</pre>

and go to the new created directory (in this example OpenOffice.org1.1_SDK) and launch the configure script which asks you relevant directories. We give here among others :
* where is your OpenOffice.org installed ? (for me /usr/lib/openoffice : noted <Ooo> later)
* Where is your Java SDK installed ? (for me /usr/java/j2sdk1.4.2_04)

Now you are ready to use the SDK. Every time you want to use it you have to launch the setsdkenv_unix script for environment variables. Automating this is not a problem under UNIX.

From now on, we will always note the SDK directory installation as : <OpenOffice.org1.1_SDK>. Please don't confuse with <Ooo> which is the openoffice.org /program/ directory.

You can find a little complement of this chapter in <OpenOffice.org1.1_SDK>/docs/install.html

The OOo2.0SDK installation is done also by launching the setsdkenv_unix script but asking more information :
<pre>
************************************************************************
*
* SDK environment is prepared for Linux
*
* SDK = /home/smoutou/openoffice.org2.0_sdk
* Office = /opt/openoffice.org2.0
* URE =
* Make = /usr/bin
* Zip = /usr/bin
* C++ Compiler = /usr/bin
* Java = /usr/java/j2sdk1.4.2_04
* Special Output directory = /home/smoutou
* Auto deployment = YES
*
************************************************************************
</pre>
If you want to check the Cpp examples, you have to launch first (as mentioned before)
<pre>
./setsdkenv_unix
</pre>
in your shell and then
<pre>
<Ooo>/program/soffice "-accept=socket,host=localhost,port=8100;urp;StarOffice.ServiceManager"
</pre>
For Openoffice.org 2.x, run instead:
<pre>
<Ooo>/program/soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager"
</pre>
Now Openoffice.org is listening on UNO connections through the network (here from localhost only).
We are ready to compile our first example and to check if it works correctly. For that we go in
<OpenOffice.org1.1_SDK>/examples/cpp/DocumentLoader directory.
<pre>
make
</pre>
will compile the example, and
<pre>
make DocumentLoader.run
</pre>
will launch the example. This example only load a Ooowriter's file (test.sxw) provided with the SDK.

Bear in mind the easier way to construct the examples of the SDK is to use the makefiles provided. When you are a beginner with the SDK you always underestimate important steps : for example the registry step discussed later. I estimate to have understand something when I am able to construct it starting with nothing (but skills). In the case of SDK this will take me a long time (and probably will not be finished). Then I can give you an advice : if you want to start a project, begin with modifying an example of the SDK.

Other SDK's examples are discussed later, but you can have a look to :

*[[Counter_Example|Counter example]]

}}

== Installation under Solaris ==
{{Documentation/Linux|
The text below describe the installation of the OpenOffic.org SDK 3.1 for OpenOffice.org3.1

The Software Development Kit (SDK) works on the top of an existing Openoffice.org installation because of using the same libraries. The SDK requires an Openoffice.org installation (default installation directory for Solaris is /opt/openoffice.org/ and /opt/openoffice.org3/)

Depending on which language you wish to use, you will need either:
The Java SDK which can be obtained [http://java.sun.com/javase/downloads/index.jsp here].
Or a C++ complier (g++ 3.0.1 or higher is recommended). As well as GNU make (3.79.1 or higher) is also essential.

First download the Solaris SDK from [http://download.openoffice.org/sdk/index.html here].

Now run the install script by typing the following command. This script will prompt you for a temporary directory where it will extract the installation package. Just press enter and the package will be extracted into the directory shown in brackets (in this case /var/tmp/unpack_openofficeorg). If you wish to extract the package into a separate directory, type in the full directory path at the prompt.

<pre>
# sh OOo-SDK_3.1.1_SolarisSparc_install_en-US.sh
Select the directory in which to save the unpacked files. [/var/tmp/unpack_openofficeorg]

File is being checked for errors ...
Unpacking ...
All files have been successfully unpacked.
</pre>

Now navigate into the packages directory under the unpacked installation directory that was just created.

<pre>
# cd /var/tmp/unpack_openofficeorg/packages
</pre>

Go ahead an install the SDK package using pfexec.

<pre>
# pfexec pkgadd -d .
</pre>

To check if the installation succeeded, attempt to navigate into the sdk directory under the OpenOffic.org basis directory.
<pre>
# cd /opt/openoffice.org/basis3.1/sdk
# ls
bin/ examples/ setsdkenv_unix.csh.in
classes/ idl/ setsdkenv_unix.sh.in
config.guess include/ settings/
config.sub index.html share/
configure.pl lib/
docs/ setsdkenv_unix
</pre>

Now you are ready to use the SDK. Every time you want to use it you have to launch the setsdkenv_unix script for environment variables. Automating this is not a problem under UNIX. You can find a little complement of this chapter in <OpenOffice.org1.1_SDK>/docs/install.html

In order to use the SDK you need to first execute the setsdkevn_unx script in the <OpenOffice.org>/basis3.1/sdk directory (/opt/openoffice.org/basis3.1/sdk for me). Before you execute this script, you need to locate all of the development tools for the language you will be using. Below is a list of the tools that the script prompts for and the locations of the tools on my machine.

<pre>
OpenOffice.org3 installation = /opt/openoffice.org3
GNU make 3.79.1 or higher = /usr/bin
C++ compiler (g++ 3.0.1 or higher) = /usr/bin
Zip = /usr/bin
Java = /usr/jdk/latest/
</pre>

Input the paths to your development tools when prompted.

You are now ready to use the OpenOffice SDK
}}

== Installation under Windows ==
{{Documentation/Windows|

You need a compiler out of the Microsoft Visual Studio family (other compilers like MinGW have turned out to be hard to configure for OOo on Windows).
The first thing after having installed the SDK is to launch the configureWindowsNT.bat and set all the necessary directories for proper use of the SDK.
If that has been done you have already installed everything, but *wait* one very important thing you should still know of:
Every time you want to run your own code or one of the SDK examples you need to launch the setsdkenv_Windows batch file from your command shell. The title of it should now be "Shell prepared for SDK". Happy coding, compiling and building now (I tell you it's easy from now on!).
GanescuCarmen describes some problems he encounter when trying SDK examples under Windows :
“I also use the 1.1 OO version.

I had a lots of problems.
Finally I succeeded to obtain the the header files, and in VC I needed some library to be included into project and some files(uno.idl) to be added to rdb files.
It was very hard to understand what it means registry(the rdb file not the Registry itself).

I was expecting to register something in Registry but it wasn't like this.
And with the service manager I had some problems, with the port, because the connection with 8100 port was not done.
I had to modify a file and to add some code for 8100 port.

But I did it and it works now.”
}}

=== Installing with the free MS Visual C++ Toolkit 2003 ===
{{Documentation/HelpNeeded|This section needs help for update because '''MS Visual C++ Toolkit 2003''' seems no more available. Please have a look at Microsoft for the free Visual C++ tools at the moment.}}
I have installed DevCpp to have a make executable file.
I have downloaded the free Visual C++ Toolkit 2003 here :
http://www.microsoft.com/downloads/details.aspx?FamilyID=272be09d-40bb-49fd-9cb0-4bfa122fa91b&displaylang=en

and then I have installed it. '''(This link is broken.)'''

I launch first C:\openoffice\OpenOffice.org2.0_SDK\configureWindowsNT.bat
which asks any questions :
<pre>
set OO_SDK_HOME=C:\openoffice\OpenOffice.org2.0_SDK
set OFFICE_HOME=C:\Program Files\OpenOffice.org 2.0
set OO_SDK_MAKE_HOME=C:\Dev-C++\Bin
set OO_SDK_CPP_HOME=C:\Program Files\Microsoft Visual C++ Toolkit 2003\Bin
set OO_SDK_JAVA_HOME=C:\Program Files\Java\jdk1.5.0_03
</pre>

and I am ready to launch setsdkenv_windows.bat

I have modified the following file :
C:\openoffice\OpenOffice.org2.0_SDK\examples\DevelopersGuide\ProfUNO\CppBinding\office_connect.cxx
to change the port accordingly to what OOo is listening.

I have modified the makefile :
added :
<pre>
CC_INCLUDES = -I"C:\Program Files\Microsoft Visual C++ Toolkit 2003\include" \
-I"C:\openoffice\OpenOffice.org2.0_SDK\include"
</pre>

and added libraries too :

<pre>
$(OUT_BIN)/%$(EXE_EXT) : $(SAMPLE_OBJ_OUT)/%.$(OBJ_EXT)
-$(MKDIR) $(subst /,$(PS),$(@D))
-$(MKDIR) $(subst /,$(PS),$(SAMPLE_GEN_OUT))
ifeq "$(OS)" "WIN"
$(LINK) $(EXE_LINK_FLAGS) /OUT:$@ /MAP:$(SAMPLE_GEN_OUT)/$(subst $(EXE_EXT),.map,$(@F)) \
$< $(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB)\
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libcp.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libc.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\oldnames.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\kernel32.lib"
else
$(LINK) $(EXE_LINK_FLAGS) $(LINK_LIBS) -o $@ $< \
$(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB) $(STDC++LIB)
endif
</pre>
I suppose there is a more straightforward way to add these libraries with adding the corresponding include path but I am unable to do that with VC++.

I find a solution of the previous problem three weeks later. My problem comes in fact from a bug in setsdkenv_windows.bat. A little correction in the file setsdkenv_windows.bat makes it possible to avoid the makefile modifications :
Put :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "C:\Program Files\Microsoft Visual C++ Toolkit 2003\VCVARS32.bat"
</pre>

instead of :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "%OO_SDK_CPP_HOME%\VCVARS32.bat"
</pre>
I think
<pre>
%OO_SDK_CPP_HOME%\..\VCVARS32.bat
</pre>
could work too (but not checked). You can also move vcvars32.bat in %OO_SDK_CPP_HOME%
("C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin" for me).

=== Other Windows Installations descriptions ===

You can find in [http://www.oooforum.org/forum/viewtopic.phtml?t=23772 OOoForum] a post entitled Guide for develop OpenOffice apps with VC++ .net (by [[CppSDKAuthors|LarsB]])

1.Download and install OpenOffice.

2.Download and install OpenOffice SDK

3.Create a new folder inludecpp in <oo_sdk_path>

4.Open Dos console change directory to <oo_sdk_path>\windows\bin

4.1 run cppumaker with followig paramerers
<pre>
cppumaker -BUCR -O <oo_sdk_path>\includecpp <office_programm_dir>\types.rdb
</pre>
or better with
<pre>
cppumaker -Gc -BUCR -O<includes_path> <ooffice_path>\URE\misc\types.rdb <ooffice_path>\Basis\program\offapi.rdb
</pre>
in recent versions.

(Attention: If you recieve a init error, copy types.rdb into the <oo_sdk_path>\windows\bin folder!)
After that all hpp and hdl files should be created in <oo_sdk_path>\includecpp

5.Open Visual Studio and create a new Win32 Console Application.
Applay the following changes to your project.

5.1. Tools ->Options->Projects->VC++ Directories -> Include Files
Add \include directory and <oo_sdk_path>\includecpp

5.2. Tools ->Options->Projects->VC++ Directories -> Library files
Add <oo_sdk_path>\windows\lib directory

5.3. Tools ->Options->Projects->VC++ Directories -> Executable files
Add <office_programm_dir>\program directory (location where you installed the version of the OpenOffice)

5.4 Open the Project Settings

5.4.1 Change Configuration to all All Configurations (the combobox in the left corner of the window)

5.4.2 Add the additional libraries

Properties->Linker->ComandLine in the Additional Options tab the library files
isal.lib icppu.lib icppuhelper.lib isal.lib isalhelper.lib ireg.lib irmcxt.lib stlport_vc71.lib

6.(example) Add the DocumentLoader.cxx from the cpp examples of the sdk
and compile. The source should compile without errors.

INFO : If you got the following error have a look at the solution 2 postings above!
Up to now, with the steps above i got the following error, when i run the DocumentLoader example.
The error is thrown, when the prog execution reach the following line:

<pre>

Reference< XSimpleRegistry > xSimpleRegistry( ::cppu::createSimpleRegistry() );
</pre>

with error shown below :

<pre>
Error:
Window title: Microsoft Visual C++ Debug Library
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

If somebody has experience with this kind of error it will be nice if he could
post a solution. So that here is a complete little guide for OpenOffice with VC++ .NET

Regards
[[CppSDKAuthors|Lars]]

[[CppSDKAuthors|François]] has improved the complete procedure with remarks :
Following all the steps I (_francois_) encountered two problems

* first in point 4.4.2

But there I guess it's because the procedure was meant for SDK 2 and I'm using SDK 1.1
The stlport_vc71.lib which you must include is distributed with the SDK 2 in the SDK 1.1 stlport_vc7.lib
you just need to include the stlport_vc7.lib instead of stlport_vc71.lib

* second problem after successfuly compiling the DocumentLoader in Visual Studio I was getting the following error
Error:
<pre>
Window title: Microsoft Visual C++ Debug Libary
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

After going on debug in the visual studio I found the following line was responsible

<pre>
xSimpleRegistry->open( OUString( RTL_CONSTASCII_USTRINGPARAM("DocumentLoader.rdb") ), sal_True, sal_False );
</pre>

The DocumentLoader.rdb was missing ... I noticed that if I compiled the DocumentLoader exemples from command line with the makefile provided with the exemple a DocumentLoader.rdb was generated. I had a look at the Makefile I isolated the lines which seemed to generate the DocumentLoader.rdb into my Debug folder (or wherever your set your DocumentLoader.exe to be put by Visual Studio) in my Visual Studio project...

<pre>
regmerge c:\travail\DocumentLoader\debug\DocumentLoader.rdb / "C:\ooo\office\program\types.rdb"

regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c connector.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c remotebridge.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c bridgefac.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c uuresolver.uno.dll
</pre>

I launched all the above lines in the prompt shell and it worked I had my DocumentLoader.rdb in my Debug folder

I launched my exe file and it worked, great...

Now I guess I still need to figure out which *.uno.dll needs to be included for which functions used in the programm, but still it's a good start.
If anyone has any information about that (It may actualy be documented somewhere) don't hesitate)

== The Development Tools of the SDK ==

There are several development tools provided with the SDK : idlc, cppumaker, javamaker, rdbmaker, pkgchk, regcomp, regmerge, regview, xml2cmp, uno, and autodoc. You can find a short documentation on these tools at <OOo_SDK>/docs/tools.html and also in [[Documentation/DevGuide/WritingUNO/Required_Files|Developer's Guide]].

See also [[Compiler_versions_used_by_port_maintainers_and_release_engineers|Compiler versions used by port maintainers and release engineers]]

{{Template:Home_Page}}

= See also =
* [[FR/Documentation/Installation_du_SDK|French version of this chapter]].
* [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno|C++ and UNO tutorial]]
* [http://www.codeproject.com/KB/wtl/Wtl_OOo.aspx Prepare the OOo SDK]
* [http://www.oooforum.org/forum/viewtopic.phtml?t=79911&highlight= missing files in sdk]
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal

[[Category:Tutorial]]
[[Category:Cpp]]
[[Category:Uno]]

SDKInstallation

2014-07-08T00:51:07Z

Global667: Put linux stuff in linux chapter

{{Documentation/Banner}}
{{Documentation/NeedsRework}}
= How to install the SDK and compile the C++ examples =

For both Linux and Windows the following points are very important if you want to succeed in building C++ components and snippets:
* you need to have OpenOffice.org 1.1.0 or higher installed (SDK won't run without it)
* you need to install the SDK into a directory other than the one of the OOo application

== Installation under Mac OS X ==
{{Documentation/OSX|
The text below describes the installation of the SDK 4.1.0 and OpenOffice 4.1.0 on Mac OS X 10.9.4 with Xcode 4.1.1. It would works for other Intel Mac configurations too.
* Install Xcode. You can get it from the Apple App Store. Perhaps you must be registered as Mac developer under https://developer.apple.com
* Install newest OpenOffice and the corresponding SDK from http://openoffice.apache.org/downloads.html (Choose MacOS_x86-64)
* Install MacPorts from http://www.macports.org. Perhaps you need to customize the path. You need MacPorts to install Unix-like software needed by the SDK.
* Test the SDK. Open a terminal and look for the SDK folder. Now type and run:
<pre>
cd <SDK_Folder>
./setsdkenv_unix
cd examples/cpp/DocumentLoader
make
soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager" & make DocumentLoader.run
</pre>
If everything went fine, you should see a new document, with the content of <SDK_Folder>/examples/cpp/DocumentLoader/test.odt.

Further informations see: http://www.openoffice.org/api/SDK/
}}

== Installation under LINUX ==
{{Documentation/Linux|
The text below describe the installation of the SDK 1.1.0 for OpenOffice.org1.1.0

The Software Development Kit (SDK) works on the top of an existing Openoffice.org installation because of using the same libraries. The SDK requires an Openoffice.org installation.
Even if you don't plan to use Java it is strongly recommended to install the JDK (1.4.1_01 or higher for OOo 1.1 SDK)
Of course a C++ compiler is needed (3.0.1 or higher). GNU make (3.79.1 or higher) is also essential.
When ready, launch :
<pre>
tar xzvf Ooo_1.1.0_LinuxIntel_sdk.tar.gz
</pre>

and go to the new created directory (in this example OpenOffice.org1.1_SDK) and launch the configure script which asks you relevant directories. We give here among others :
* where is your OpenOffice.org installed ? (for me /usr/lib/openoffice : noted <Ooo> later)
* Where is your Java SDK installed ? (for me /usr/java/j2sdk1.4.2_04)

Now you are ready to use the SDK. Every time you want to use it you have to launch the setsdkenv_unix script for environment variables. Automating this is not a problem under UNIX.

From now on, we will always note the SDK directory installation as : <OpenOffice.org1.1_SDK>. Please don't confuse with <Ooo> which is the openoffice.org /program/ directory.

You can find a little complement of this chapter in <OpenOffice.org1.1_SDK>/docs/install.html

The OOo2.0SDK installation is done also by launching the setsdkenv_unix script but asking more information :
<pre>
************************************************************************
*
* SDK environment is prepared for Linux
*
* SDK = /home/smoutou/openoffice.org2.0_sdk
* Office = /opt/openoffice.org2.0
* URE =
* Make = /usr/bin
* Zip = /usr/bin
* C++ Compiler = /usr/bin
* Java = /usr/java/j2sdk1.4.2_04
* Special Output directory = /home/smoutou
* Auto deployment = YES
*
************************************************************************
</pre>
If you want to check the Cpp examples, you have to launch first (as mentioned before)
<pre>
./setsdkenv_unix
</pre>
in your shell and then
<pre>
<Ooo>/program/soffice "-accept=socket,host=localhost,port=8100;urp;StarOffice.ServiceManager"
</pre>
For Openoffice.org 2.x, run instead:
<pre>
<Ooo>/program/soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager"
</pre>
Now Openoffice.org is listening on UNO connections through the network (here from localhost only).
We are ready to compile our first example and to check if it works correctly. For that we go in
<OpenOffice.org1.1_SDK>/examples/cpp/DocumentLoader directory.
<pre>
make
</pre>
will compile the example, and
<pre>
make DocumentLoader.run
</pre>
will launch the example. This example only load a Ooowriter's file (test.sxw) provided with the SDK.

Bear in mind the easier way to construct the examples of the SDK is to use the makefiles provided. When you are a beginner with the SDK you always underestimate important steps : for example the registry step discussed later. I estimate to have understand something when I am able to construct it starting with nothing (but skills). In the case of SDK this will take me a long time (and probably will not be finished). Then I can give you an advice : if you want to start a project, begin with modifying an example of the SDK.

Other SDK's examples are discussed later, but you can have a look to :

*[[Counter_Example|Counter example]]

}}

== Installation under Solaris ==
{{Documentation/Linux|
The text below describe the installation of the OpenOffic.org SDK 3.1 for OpenOffice.org3.1

The Software Development Kit (SDK) works on the top of an existing Openoffice.org installation because of using the same libraries. The SDK requires an Openoffice.org installation (default installation directory for Solaris is /opt/openoffice.org/ and /opt/openoffice.org3/)

Depending on which language you wish to use, you will need either:
The Java SDK which can be obtained [http://java.sun.com/javase/downloads/index.jsp here].
Or a C++ complier (g++ 3.0.1 or higher is recommended). As well as GNU make (3.79.1 or higher) is also essential.

First download the Solaris SDK from [http://download.openoffice.org/sdk/index.html here].

Now run the install script by typing the following command. This script will prompt you for a temporary directory where it will extract the installation package. Just press enter and the package will be extracted into the directory shown in brackets (in this case /var/tmp/unpack_openofficeorg). If you wish to extract the package into a separate directory, type in the full directory path at the prompt.

<pre>
# sh OOo-SDK_3.1.1_SolarisSparc_install_en-US.sh
Select the directory in which to save the unpacked files. [/var/tmp/unpack_openofficeorg]

File is being checked for errors ...
Unpacking ...
All files have been successfully unpacked.
</pre>

Now navigate into the packages directory under the unpacked installation directory that was just created.

<pre>
# cd /var/tmp/unpack_openofficeorg/packages
</pre>

Go ahead an install the SDK package using pfexec.

<pre>
# pfexec pkgadd -d .
</pre>

To check if the installation succeeded, attempt to navigate into the sdk directory under the OpenOffic.org basis directory.
<pre>
# cd /opt/openoffice.org/basis3.1/sdk
# ls
bin/ examples/ setsdkenv_unix.csh.in
classes/ idl/ setsdkenv_unix.sh.in
config.guess include/ settings/
config.sub index.html share/
configure.pl lib/
docs/ setsdkenv_unix
</pre>

Now you are ready to use the SDK. Every time you want to use it you have to launch the setsdkenv_unix script for environment variables. Automating this is not a problem under UNIX. You can find a little complement of this chapter in <OpenOffice.org1.1_SDK>/docs/install.html

In order to use the SDK you need to first execute the setsdkevn_unx script in the <OpenOffice.org>/basis3.1/sdk directory (/opt/openoffice.org/basis3.1/sdk for me). Before you execute this script, you need to locate all of the development tools for the language you will be using. Below is a list of the tools that the script prompts for and the locations of the tools on my machine.

<pre>
OpenOffice.org3 installation = /opt/openoffice.org3
GNU make 3.79.1 or higher = /usr/bin
C++ compiler (g++ 3.0.1 or higher) = /usr/bin
Zip = /usr/bin
Java = /usr/jdk/latest/
</pre>

Input the paths to your development tools when prompted.

You are now ready to use the OpenOffice SDK
}}

== Installation under Windows ==
{{Documentation/Windows|

You need a compiler out of the Microsoft Visual Studio family (other compilers like MinGW have turned out to be hard to configure for OOo on Windows).
The first thing after having installed the SDK is to launch the configureWindowsNT.bat and set all the necessary directories for proper use of the SDK.
If that has been done you have already installed everything, but *wait* one very important thing you should still know of:
Every time you want to run your own code or one of the SDK examples you need to launch the setsdkenv_Windows batch file from your command shell. The title of it should now be "Shell prepared for SDK". Happy coding, compiling and building now (I tell you it's easy from now on!).
GanescuCarmen describes some problems he encounter when trying SDK examples under Windows :
“I also use the 1.1 OO version.

I had a lots of problems.
Finally I succeeded to obtain the the header files, and in VC I needed some library to be included into project and some files(uno.idl) to be added to rdb files.
It was very hard to understand what it means registry(the rdb file not the Registry itself).

I was expecting to register something in Registry but it wasn't like this.
And with the service manager I had some problems, with the port, because the connection with 8100 port was not done.
I had to modify a file and to add some code for 8100 port.

But I did it and it works now.”
}}

== Installing with the free MS Visual C++ Toolkit 2003 ==
{{Documentation/HelpNeeded|This section needs help for update because '''MS Visual C++ Toolkit 2003''' seems no more available. Please have a look at Microsoft for the free Visual C++ tools at the moment.}}
I have installed DevCpp to have a make executable file.
I have downloaded the free Visual C++ Toolkit 2003 here :
http://www.microsoft.com/downloads/details.aspx?FamilyID=272be09d-40bb-49fd-9cb0-4bfa122fa91b&displaylang=en

and then I have installed it. '''(This link is broken.)'''

I launch first C:\openoffice\OpenOffice.org2.0_SDK\configureWindowsNT.bat
which asks any questions :
<pre>
set OO_SDK_HOME=C:\openoffice\OpenOffice.org2.0_SDK
set OFFICE_HOME=C:\Program Files\OpenOffice.org 2.0
set OO_SDK_MAKE_HOME=C:\Dev-C++\Bin
set OO_SDK_CPP_HOME=C:\Program Files\Microsoft Visual C++ Toolkit 2003\Bin
set OO_SDK_JAVA_HOME=C:\Program Files\Java\jdk1.5.0_03
</pre>

and I am ready to launch setsdkenv_windows.bat

I have modified the following file :
C:\openoffice\OpenOffice.org2.0_SDK\examples\DevelopersGuide\ProfUNO\CppBinding\office_connect.cxx
to change the port accordingly to what OOo is listening.

I have modified the makefile :
added :
<pre>
CC_INCLUDES = -I"C:\Program Files\Microsoft Visual C++ Toolkit 2003\include" \
-I"C:\openoffice\OpenOffice.org2.0_SDK\include"
</pre>

and added libraries too :

<pre>
$(OUT_BIN)/%$(EXE_EXT) : $(SAMPLE_OBJ_OUT)/%.$(OBJ_EXT)
-$(MKDIR) $(subst /,$(PS),$(@D))
-$(MKDIR) $(subst /,$(PS),$(SAMPLE_GEN_OUT))
ifeq "$(OS)" "WIN"
$(LINK) $(EXE_LINK_FLAGS) /OUT:$@ /MAP:$(SAMPLE_GEN_OUT)/$(subst $(EXE_EXT),.map,$(@F)) \
$< $(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB)\
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libcp.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libc.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\oldnames.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\kernel32.lib"
else
$(LINK) $(EXE_LINK_FLAGS) $(LINK_LIBS) -o $@ $< \
$(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB) $(STDC++LIB)
endif
</pre>
I suppose there is a more straightforward way to add these libraries with adding the corresponding include path but I am unable to do that with VC++.

I find a solution of the previous problem three weeks later. My problem comes in fact from a bug in setsdkenv_windows.bat. A little correction in the file setsdkenv_windows.bat makes it possible to avoid the makefile modifications :
Put :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "C:\Program Files\Microsoft Visual C++ Toolkit 2003\VCVARS32.bat"
</pre>

instead of :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "%OO_SDK_CPP_HOME%\VCVARS32.bat"
</pre>
I think
<pre>
%OO_SDK_CPP_HOME%\..\VCVARS32.bat
</pre>
could work too (but not checked). You can also move vcvars32.bat in %OO_SDK_CPP_HOME%
("C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin" for me).

== Other Windows Installations descriptions ==

You can find in [http://www.oooforum.org/forum/viewtopic.phtml?t=23772 OOoForum] a post entitled Guide for develop OpenOffice apps with VC++ .net (by [[CppSDKAuthors|LarsB]])

1.Download and install OpenOffice.

2.Download and install OpenOffice SDK

3.Create a new folder inludecpp in <oo_sdk_path>

4.Open Dos console change directory to <oo_sdk_path>\windows\bin

4.1 run cppumaker with followig paramerers
<pre>
cppumaker -BUCR -O <oo_sdk_path>\includecpp <office_programm_dir>\types.rdb
</pre>
or better with
<pre>
cppumaker -Gc -BUCR -O<includes_path> <ooffice_path>\URE\misc\types.rdb <ooffice_path>\Basis\program\offapi.rdb
</pre>
in recent versions.

(Attention: If you recieve a init error, copy types.rdb into the <oo_sdk_path>\windows\bin folder!)
After that all hpp and hdl files should be created in <oo_sdk_path>\includecpp

5.Open Visual Studio and create a new Win32 Console Application.
Applay the following changes to your project.

5.1. Tools ->Options->Projects->VC++ Directories -> Include Files
Add \include directory and <oo_sdk_path>\includecpp

5.2. Tools ->Options->Projects->VC++ Directories -> Library files
Add <oo_sdk_path>\windows\lib directory

5.3. Tools ->Options->Projects->VC++ Directories -> Executable files
Add <office_programm_dir>\program directory (location where you installed the version of the OpenOffice)

5.4 Open the Project Settings

5.4.1 Change Configuration to all All Configurations (the combobox in the left corner of the window)

5.4.2 Add the additional libraries

Properties->Linker->ComandLine in the Additional Options tab the library files
isal.lib icppu.lib icppuhelper.lib isal.lib isalhelper.lib ireg.lib irmcxt.lib stlport_vc71.lib

6.(example) Add the DocumentLoader.cxx from the cpp examples of the sdk
and compile. The source should compile without errors.

INFO : If you got the following error have a look at the solution 2 postings above!
Up to now, with the steps above i got the following error, when i run the DocumentLoader example.
The error is thrown, when the prog execution reach the following line:

<pre>

Reference< XSimpleRegistry > xSimpleRegistry( ::cppu::createSimpleRegistry() );
</pre>

with error shown below :

<pre>
Error:
Window title: Microsoft Visual C++ Debug Library
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

If somebody has experience with this kind of error it will be nice if he could
post a solution. So that here is a complete little guide for OpenOffice with VC++ .NET

Regards
[[CppSDKAuthors|Lars]]

[[CppSDKAuthors|François]] has improved the complete procedure with remarks :
Following all the steps I (_francois_) encountered two problems

* first in point 4.4.2

But there I guess it's because the procedure was meant for SDK 2 and I'm using SDK 1.1
The stlport_vc71.lib which you must include is distributed with the SDK 2 in the SDK 1.1 stlport_vc7.lib
you just need to include the stlport_vc7.lib instead of stlport_vc71.lib

* second problem after successfuly compiling the DocumentLoader in Visual Studio I was getting the following error
Error:
<pre>
Window title: Microsoft Visual C++ Debug Libary
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

After going on debug in the visual studio I found the following line was responsible

<pre>
xSimpleRegistry->open( OUString( RTL_CONSTASCII_USTRINGPARAM("DocumentLoader.rdb") ), sal_True, sal_False );
</pre>

The DocumentLoader.rdb was missing ... I noticed that if I compiled the DocumentLoader exemples from command line with the makefile provided with the exemple a DocumentLoader.rdb was generated. I had a look at the Makefile I isolated the lines which seemed to generate the DocumentLoader.rdb into my Debug folder (or wherever your set your DocumentLoader.exe to be put by Visual Studio) in my Visual Studio project...

<pre>
regmerge c:\travail\DocumentLoader\debug\DocumentLoader.rdb / "C:\ooo\office\program\types.rdb"

regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c connector.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c remotebridge.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c bridgefac.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c uuresolver.uno.dll
</pre>

I launched all the above lines in the prompt shell and it worked I had my DocumentLoader.rdb in my Debug folder

I launched my exe file and it worked, great...

Now I guess I still need to figure out which *.uno.dll needs to be included for which functions used in the programm, but still it's a good start.
If anyone has any information about that (It may actualy be documented somewhere) don't hesitate)

== The Development Tools of the SDK ==

There are several development tools provided with the SDK : idlc, cppumaker, javamaker, rdbmaker, pkgchk, regcomp, regmerge, regview, xml2cmp, uno, and autodoc. You can find a short documentation on these tools at <OOo_SDK>/docs/tools.html and also in [[Documentation/DevGuide/WritingUNO/Required_Files|Developer's Guide]].

See also [[Compiler_versions_used_by_port_maintainers_and_release_engineers|Compiler versions used by port maintainers and release engineers]]

{{Template:Home_Page}}

= See also =
* [[FR/Documentation/Installation_du_SDK|French version of this chapter]].
* [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno|C++ and UNO tutorial]]
* [http://www.codeproject.com/KB/wtl/Wtl_OOo.aspx Prepare the OOo SDK]
* [http://www.oooforum.org/forum/viewtopic.phtml?t=79911&highlight= missing files in sdk]
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal

[[Category:Tutorial]]
[[Category:Cpp]]
[[Category:Uno]]

SDKInstallation

2014-07-08T00:22:41Z

Global667: /* Installation under Mac OS X (Intel processors) */ Make it more general

{{Documentation/Banner}}
{{Documentation/NeedsRework}}
= How to install the SDK and compile the C++ examples =

For both Linux and Windows the following points are very important if you want to succeed in building C++ components and snippets:
* you need to have OpenOffice.org 1.1.0 or higher installed (SDK won't run without it)
* you need to install the SDK into a directory other than the one of the OOo application

== Installation under Mac OS X ==
{{Documentation/OSX|
The text below describes the installation of the SDK 4.1.0 and OpenOffice 4.1.0 on Mac OS X 10.9.4 with Xcode 4.1.1. It would works for other Intel Mac configurations too.
* Install Xcode. You can get it from the Apple App Store. Perhaps you must be registered as Mac developer under https://developer.apple.com
* Install newest OpenOffice and the corresponding SDK from http://openoffice.apache.org/downloads.html (Choose MacOS_x86-64)
* Install MacPorts from http://www.macports.org. Perhaps you need to customize the path. You need MacPorts to install Unix-like software needed by the SDK.
* Test the SDK. Open a terminal and look for the SDK folder. Now type and run:
<pre>
cd <SDK_Folder>
./setsdkenv_unix
cd examples/cpp/DocumentLoader
make
soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager" & make DocumentLoader.run
</pre>
If everything went fine, you should see a new document, with the content of <SDK_Folder>/examples/cpp/DocumentLoader/test.odt.

Further informations see: http://www.openoffice.org/api/SDK/
}}

== Installation under LINUX ==
{{Documentation/Linux|
The text below describe the installation of the SDK 1.1.0 for OpenOffice.org1.1.0

The Software Development Kit (SDK) works on the top of an existing Openoffice.org installation because of using the same libraries. The SDK requires an Openoffice.org installation.
Even if you don't plan to use Java it is strongly recommended to install the JDK (1.4.1_01 or higher for OOo 1.1 SDK)
Of course a C++ compiler is needed (3.0.1 or higher). GNU make (3.79.1 or higher) is also essential.
When ready, launch :
<pre>
tar xzvf Ooo_1.1.0_LinuxIntel_sdk.tar.gz
</pre>

and go to the new created directory (in this example OpenOffice.org1.1_SDK) and launch the configure script which asks you relevant directories. We give here among others :
* where is your OpenOffice.org installed ? (for me /usr/lib/openoffice : noted <Ooo> later)
* Where is your Java SDK installed ? (for me /usr/java/j2sdk1.4.2_04)

Now you are ready to use the SDK. Every time you want to use it you have to launch the setsdkenv_unix script for environment variables. Automating this is not a problem under UNIX.

From now on, we will always note the SDK directory installation as : <OpenOffice.org1.1_SDK>. Please don't confuse with <Ooo> which is the openoffice.org /program/ directory.

You can find a little complement of this chapter in <OpenOffice.org1.1_SDK>/docs/install.html

The OOo2.0SDK installation is done also by launching the setsdkenv_unix script but asking more information :
<pre>
************************************************************************
*
* SDK environment is prepared for Linux
*
* SDK = /home/smoutou/openoffice.org2.0_sdk
* Office = /opt/openoffice.org2.0
* URE =
* Make = /usr/bin
* Zip = /usr/bin
* C++ Compiler = /usr/bin
* Java = /usr/java/j2sdk1.4.2_04
* Special Output directory = /home/smoutou
* Auto deployment = YES
*
************************************************************************

</pre>
}}

== Installation under Solaris ==
{{Documentation/Linux|
The text below describe the installation of the OpenOffic.org SDK 3.1 for OpenOffice.org3.1

The Software Development Kit (SDK) works on the top of an existing Openoffice.org installation because of using the same libraries. The SDK requires an Openoffice.org installation (default installation directory for Solaris is /opt/openoffice.org/ and /opt/openoffice.org3/)

Depending on which language you wish to use, you will need either:
The Java SDK which can be obtained [http://java.sun.com/javase/downloads/index.jsp here].
Or a C++ complier (g++ 3.0.1 or higher is recommended). As well as GNU make (3.79.1 or higher) is also essential.

First download the Solaris SDK from [http://download.openoffice.org/sdk/index.html here].

Now run the install script by typing the following command. This script will prompt you for a temporary directory where it will extract the installation package. Just press enter and the package will be extracted into the directory shown in brackets (in this case /var/tmp/unpack_openofficeorg). If you wish to extract the package into a separate directory, type in the full directory path at the prompt.

<pre>
# sh OOo-SDK_3.1.1_SolarisSparc_install_en-US.sh
Select the directory in which to save the unpacked files. [/var/tmp/unpack_openofficeorg]

File is being checked for errors ...
Unpacking ...
All files have been successfully unpacked.
</pre>

Now navigate into the packages directory under the unpacked installation directory that was just created.

<pre>
# cd /var/tmp/unpack_openofficeorg/packages
</pre>

Go ahead an install the SDK package using pfexec.

<pre>
# pfexec pkgadd -d .
</pre>

To check if the installation succeeded, attempt to navigate into the sdk directory under the OpenOffic.org basis directory.
<pre>
# cd /opt/openoffice.org/basis3.1/sdk
# ls
bin/ examples/ setsdkenv_unix.csh.in
classes/ idl/ setsdkenv_unix.sh.in
config.guess include/ settings/
config.sub index.html share/
configure.pl lib/
docs/ setsdkenv_unix
</pre>

Now you are ready to use the SDK. Every time you want to use it you have to launch the setsdkenv_unix script for environment variables. Automating this is not a problem under UNIX. You can find a little complement of this chapter in <OpenOffice.org1.1_SDK>/docs/install.html

In order to use the SDK you need to first execute the setsdkevn_unx script in the <OpenOffice.org>/basis3.1/sdk directory (/opt/openoffice.org/basis3.1/sdk for me). Before you execute this script, you need to locate all of the development tools for the language you will be using. Below is a list of the tools that the script prompts for and the locations of the tools on my machine.

<pre>
OpenOffice.org3 installation = /opt/openoffice.org3
GNU make 3.79.1 or higher = /usr/bin
C++ compiler (g++ 3.0.1 or higher) = /usr/bin
Zip = /usr/bin
Java = /usr/jdk/latest/
</pre>

Input the paths to your development tools when prompted.

You are now ready to use the OpenOffice SDK
}}

== Installation under Windows ==
{{Documentation/Windows|

You need a compiler out of the Microsoft Visual Studio family (other compilers like MinGW have turned out to be hard to configure for OOo on Windows).
The first thing after having installed the SDK is to launch the configureWindowsNT.bat and set all the necessary directories for proper use of the SDK.
If that has been done you have already installed everything, but *wait* one very important thing you should still know of:
Every time you want to run your own code or one of the SDK examples you need to launch the setsdkenv_Windows batch file from your command shell. The title of it should now be "Shell prepared for SDK". Happy coding, compiling and building now (I tell you it's easy from now on!).
GanescuCarmen describes some problems he encounter when trying SDK examples under Windows :
“I also use the 1.1 OO version.

I had a lots of problems.
Finally I succeeded to obtain the the header files, and in VC I needed some library to be included into project and some files(uno.idl) to be added to rdb files.
It was very hard to understand what it means registry(the rdb file not the Registry itself).

I was expecting to register something in Registry but it wasn't like this.
And with the service manager I had some problems, with the port, because the connection with 8100 port was not done.
I had to modify a file and to add some code for 8100 port.

But I did it and it works now.”
}}

== Installing with the free MS Visual C++ Toolkit 2003 ==
{{Documentation/HelpNeeded|This section needs help for update because '''MS Visual C++ Toolkit 2003''' seems no more available. Please have a look at Microsoft for the free Visual C++ tools at the moment.}}
I have installed DevCpp to have a make executable file.
I have downloaded the free Visual C++ Toolkit 2003 here :
http://www.microsoft.com/downloads/details.aspx?FamilyID=272be09d-40bb-49fd-9cb0-4bfa122fa91b&displaylang=en

and then I have installed it. '''(This link is broken.)'''

I launch first C:\openoffice\OpenOffice.org2.0_SDK\configureWindowsNT.bat
which asks any questions :
<pre>
set OO_SDK_HOME=C:\openoffice\OpenOffice.org2.0_SDK
set OFFICE_HOME=C:\Program Files\OpenOffice.org 2.0
set OO_SDK_MAKE_HOME=C:\Dev-C++\Bin
set OO_SDK_CPP_HOME=C:\Program Files\Microsoft Visual C++ Toolkit 2003\Bin
set OO_SDK_JAVA_HOME=C:\Program Files\Java\jdk1.5.0_03
</pre>

and I am ready to launch setsdkenv_windows.bat

I have modified the following file :
C:\openoffice\OpenOffice.org2.0_SDK\examples\DevelopersGuide\ProfUNO\CppBinding\office_connect.cxx
to change the port accordingly to what OOo is listening.

I have modified the makefile :
added :
<pre>
CC_INCLUDES = -I"C:\Program Files\Microsoft Visual C++ Toolkit 2003\include" \
-I"C:\openoffice\OpenOffice.org2.0_SDK\include"
</pre>

and added libraries too :

<pre>
$(OUT_BIN)/%$(EXE_EXT) : $(SAMPLE_OBJ_OUT)/%.$(OBJ_EXT)
-$(MKDIR) $(subst /,$(PS),$(@D))
-$(MKDIR) $(subst /,$(PS),$(SAMPLE_GEN_OUT))
ifeq "$(OS)" "WIN"
$(LINK) $(EXE_LINK_FLAGS) /OUT:$@ /MAP:$(SAMPLE_GEN_OUT)/$(subst $(EXE_EXT),.map,$(@F)) \
$< $(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB)\
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libcp.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libc.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\oldnames.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\kernel32.lib"
else
$(LINK) $(EXE_LINK_FLAGS) $(LINK_LIBS) -o $@ $< \
$(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB) $(STDC++LIB)
endif
</pre>
I suppose there is a more straightforward way to add these libraries with adding the corresponding include path but I am unable to do that with VC++.

I find a solution of the previous problem three weeks later. My problem comes in fact from a bug in setsdkenv_windows.bat. A little correction in the file setsdkenv_windows.bat makes it possible to avoid the makefile modifications :
Put :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "C:\Program Files\Microsoft Visual C++ Toolkit 2003\VCVARS32.bat"
</pre>

instead of :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "%OO_SDK_CPP_HOME%\VCVARS32.bat"
</pre>
I think
<pre>
%OO_SDK_CPP_HOME%\..\VCVARS32.bat
</pre>
could work too (but not checked). You can also move vcvars32.bat in %OO_SDK_CPP_HOME%
("C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin" for me).

== Other Windows Installations descriptions ==

You can find in [http://www.oooforum.org/forum/viewtopic.phtml?t=23772 OOoForum] a post entitled Guide for develop OpenOffice apps with VC++ .net (by [[CppSDKAuthors|LarsB]])

1.Download and install OpenOffice.

2.Download and install OpenOffice SDK

3.Create a new folder inludecpp in <oo_sdk_path>

4.Open Dos console change directory to <oo_sdk_path>\windows\bin

4.1 run cppumaker with followig paramerers
<pre>
cppumaker -BUCR -O <oo_sdk_path>\includecpp <office_programm_dir>\types.rdb
</pre>
or better with
<pre>
cppumaker -Gc -BUCR -O<includes_path> <ooffice_path>\URE\misc\types.rdb <ooffice_path>\Basis\program\offapi.rdb
</pre>
in recent versions.

(Attention: If you recieve a init error, copy types.rdb into the <oo_sdk_path>\windows\bin folder!)
After that all hpp and hdl files should be created in <oo_sdk_path>\includecpp

5.Open Visual Studio and create a new Win32 Console Application.
Applay the following changes to your project.

5.1. Tools ->Options->Projects->VC++ Directories -> Include Files
Add \include directory and <oo_sdk_path>\includecpp

5.2. Tools ->Options->Projects->VC++ Directories -> Library files
Add <oo_sdk_path>\windows\lib directory

5.3. Tools ->Options->Projects->VC++ Directories -> Executable files
Add <office_programm_dir>\program directory (location where you installed the version of the OpenOffice)

5.4 Open the Project Settings

5.4.1 Change Configuration to all All Configurations (the combobox in the left corner of the window)

5.4.2 Add the additional libraries

Properties->Linker->ComandLine in the Additional Options tab the library files
isal.lib icppu.lib icppuhelper.lib isal.lib isalhelper.lib ireg.lib irmcxt.lib stlport_vc71.lib

6.(example) Add the DocumentLoader.cxx from the cpp examples of the sdk
and compile. The source should compile without errors.

INFO : If you got the following error have a look at the solution 2 postings above!
Up to now, with the steps above i got the following error, when i run the DocumentLoader example.
The error is thrown, when the prog execution reach the following line:

<pre>

Reference< XSimpleRegistry > xSimpleRegistry( ::cppu::createSimpleRegistry() );
</pre>

with error shown below :

<pre>
Error:
Window title: Microsoft Visual C++ Debug Library
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

If somebody has experience with this kind of error it will be nice if he could
post a solution. So that here is a complete little guide for OpenOffice with VC++ .NET

Regards
[[CppSDKAuthors|Lars]]

[[CppSDKAuthors|François]] has improved the complete procedure with remarks :
Following all the steps I (_francois_) encountered two problems

* first in point 4.4.2

But there I guess it's because the procedure was meant for SDK 2 and I'm using SDK 1.1
The stlport_vc71.lib which you must include is distributed with the SDK 2 in the SDK 1.1 stlport_vc7.lib
you just need to include the stlport_vc7.lib instead of stlport_vc71.lib

* second problem after successfuly compiling the DocumentLoader in Visual Studio I was getting the following error
Error:
<pre>
Window title: Microsoft Visual C++ Debug Libary
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

After going on debug in the visual studio I found the following line was responsible

<pre>
xSimpleRegistry->open( OUString( RTL_CONSTASCII_USTRINGPARAM("DocumentLoader.rdb") ), sal_True, sal_False );
</pre>

The DocumentLoader.rdb was missing ... I noticed that if I compiled the DocumentLoader exemples from command line with the makefile provided with the exemple a DocumentLoader.rdb was generated. I had a look at the Makefile I isolated the lines which seemed to generate the DocumentLoader.rdb into my Debug folder (or wherever your set your DocumentLoader.exe to be put by Visual Studio) in my Visual Studio project...

<pre>
regmerge c:\travail\DocumentLoader\debug\DocumentLoader.rdb / "C:\ooo\office\program\types.rdb"

regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c connector.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c remotebridge.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c bridgefac.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c uuresolver.uno.dll
</pre>

I launched all the above lines in the prompt shell and it worked I had my DocumentLoader.rdb in my Debug folder

I launched my exe file and it worked, great...

Now I guess I still need to figure out which *.uno.dll needs to be included for which functions used in the programm, but still it's a good start.
If anyone has any information about that (It may actualy be documented somewhere) don't hesitate)

== The Development Tools of the SDK ==

There are several development tools provided with the SDK : idlc, cppumaker, javamaker, rdbmaker, pkgchk, regcomp, regmerge, regview, xml2cmp, uno, and autodoc. You can find a short documentation on these tools at <OOo_SDK>/docs/tools.html and also in [[Documentation/DevGuide/WritingUNO/Required_Files|Developer's Guide]].

See also [[Compiler_versions_used_by_port_maintainers_and_release_engineers|Compiler versions used by port maintainers and release engineers]]

== One Cpp Example ==
If you want to check the Cpp examples, you have to launch first (as mentioned before)
{{Documentation/Linux|
<pre>
./setsdkenv_unix
</pre>
}}
in your shell and then
{{Documentation/Linux|
<pre>
<Ooo>/program/soffice "-accept=socket,host=localhost,port=8100;urp;StarOffice.ServiceManager"
</pre>
}}
For Openoffice.org 2.x, run instead:
{{Documentation/Linux|
<pre>
<Ooo>/program/soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager"
</pre>
}}
Now Openoffice.org is listening on UNO connections through the network (here from localhost only).
We are ready to compile our first example and to check if it works correctly. For that we go in
<OpenOffice.org1.1_SDK>/examples/cpp/DocumentLoader directory.
<pre>
make
</pre>
will compile the example, and
<pre>
make DocumentLoader.run
</pre>
will launch the example. This example only load a Ooowriter's file (test.sxw) provided with the SDK.

Bear in mind the easier way to construct the examples of the SDK is to use the makefiles provided. When you are a beginner with the SDK you always underestimate important steps : for example the registry step discussed later. I estimate to have understand something when I am able to construct it starting with nothing (but skills). In the case of SDK this will take me a long time (and probably will not be finished). Then I can give you an advice : if you want to start a project, begin with modifying an example of the SDK.

Other SDK's examples are discussed later, but you can have a look to :

*[[Counter_Example|Counter example]]

{{Template:Home_Page}}

= See also =
* [[FR/Documentation/Installation_du_SDK|French version of this chapter]].
* [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno|C++ and UNO tutorial]]
* [http://www.codeproject.com/KB/wtl/Wtl_OOo.aspx Prepare the OOo SDK]
* [http://www.oooforum.org/forum/viewtopic.phtml?t=79911&highlight= missing files in sdk]
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal

[[Category:Tutorial]]
[[Category:Cpp]]
[[Category:Uno]]

SDKInstallation

2014-07-07T23:00:54Z

Global667: /* Installation under Mac OS X (Intel processors) */ wrong link

{{Documentation/Banner}}
{{Documentation/NeedsRework}}
= How to install the SDK and compile the C++ examples =

For both Linux and Windows the following points are very important if you want to succeed in building C++ components and snippets:
* you need to have OpenOffice.org 1.1.0 or higher installed (SDK won't run without it)
* you need to install the SDK into a directory other than the one of the OOo application

== Installation under Mac OS X (Intel processors) ==
{{Documentation/OSX|
The text below describes the installation of the SDK 4.1 on Mac OS X 10.9.4 with Xcode 4.1.1. It would works for other configurations too.
* Install Xcode. You can get it from the Apple App Store. Perhaps you must be registered as Mac developer under https://developer.apple.com
* Install OpenOffice 4.1
* Install MacPorts from http://www.macports.org. Perhaps you need to customize the path. You need MacPorts to install Unix-like software needed by the SDK.
* Install the SDK from http://openoffice.apache.org/downloads.html (You need 4.1.0 for MacOS_x86-64)
* Test the SDK. Open a terminal and look for the SDK folder. Now type and run:
<pre>
cd <SDK_Folder>
./setsdkenv_unix
cd examples/cpp/DocumentLoader
make
soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager" & make DocumentLoader.run
</pre>
If everything went fine, you should see a new document, with the content of <SDK_Folder>/examples/cpp/DocumentLoader/test.odt.

Further informations see: http://www.openoffice.org/api/SDK/
}}

== Installation under LINUX ==
{{Documentation/Linux|
The text below describe the installation of the SDK 1.1.0 for OpenOffice.org1.1.0

The Software Development Kit (SDK) works on the top of an existing Openoffice.org installation because of using the same libraries. The SDK requires an Openoffice.org installation.
Even if you don't plan to use Java it is strongly recommended to install the JDK (1.4.1_01 or higher for OOo 1.1 SDK)
Of course a C++ compiler is needed (3.0.1 or higher). GNU make (3.79.1 or higher) is also essential.
When ready, launch :
<pre>
tar xzvf Ooo_1.1.0_LinuxIntel_sdk.tar.gz
</pre>

and go to the new created directory (in this example OpenOffice.org1.1_SDK) and launch the configure script which asks you relevant directories. We give here among others :
* where is your OpenOffice.org installed ? (for me /usr/lib/openoffice : noted <Ooo> later)
* Where is your Java SDK installed ? (for me /usr/java/j2sdk1.4.2_04)

Now you are ready to use the SDK. Every time you want to use it you have to launch the setsdkenv_unix script for environment variables. Automating this is not a problem under UNIX.

From now on, we will always note the SDK directory installation as : <OpenOffice.org1.1_SDK>. Please don't confuse with <Ooo> which is the openoffice.org /program/ directory.

You can find a little complement of this chapter in <OpenOffice.org1.1_SDK>/docs/install.html

The OOo2.0SDK installation is done also by launching the setsdkenv_unix script but asking more information :
<pre>
************************************************************************
*
* SDK environment is prepared for Linux
*
* SDK = /home/smoutou/openoffice.org2.0_sdk
* Office = /opt/openoffice.org2.0
* URE =
* Make = /usr/bin
* Zip = /usr/bin
* C++ Compiler = /usr/bin
* Java = /usr/java/j2sdk1.4.2_04
* Special Output directory = /home/smoutou
* Auto deployment = YES
*
************************************************************************

</pre>
}}

== Installation under Solaris ==
{{Documentation/Linux|
The text below describe the installation of the OpenOffic.org SDK 3.1 for OpenOffice.org3.1

The Software Development Kit (SDK) works on the top of an existing Openoffice.org installation because of using the same libraries. The SDK requires an Openoffice.org installation (default installation directory for Solaris is /opt/openoffice.org/ and /opt/openoffice.org3/)

Depending on which language you wish to use, you will need either:
The Java SDK which can be obtained [http://java.sun.com/javase/downloads/index.jsp here].
Or a C++ complier (g++ 3.0.1 or higher is recommended). As well as GNU make (3.79.1 or higher) is also essential.

First download the Solaris SDK from [http://download.openoffice.org/sdk/index.html here].

Now run the install script by typing the following command. This script will prompt you for a temporary directory where it will extract the installation package. Just press enter and the package will be extracted into the directory shown in brackets (in this case /var/tmp/unpack_openofficeorg). If you wish to extract the package into a separate directory, type in the full directory path at the prompt.

<pre>
# sh OOo-SDK_3.1.1_SolarisSparc_install_en-US.sh
Select the directory in which to save the unpacked files. [/var/tmp/unpack_openofficeorg]

File is being checked for errors ...
Unpacking ...
All files have been successfully unpacked.
</pre>

Now navigate into the packages directory under the unpacked installation directory that was just created.

<pre>
# cd /var/tmp/unpack_openofficeorg/packages
</pre>

Go ahead an install the SDK package using pfexec.

<pre>
# pfexec pkgadd -d .
</pre>

To check if the installation succeeded, attempt to navigate into the sdk directory under the OpenOffic.org basis directory.
<pre>
# cd /opt/openoffice.org/basis3.1/sdk
# ls
bin/ examples/ setsdkenv_unix.csh.in
classes/ idl/ setsdkenv_unix.sh.in
config.guess include/ settings/
config.sub index.html share/
configure.pl lib/
docs/ setsdkenv_unix
</pre>

Now you are ready to use the SDK. Every time you want to use it you have to launch the setsdkenv_unix script for environment variables. Automating this is not a problem under UNIX. You can find a little complement of this chapter in <OpenOffice.org1.1_SDK>/docs/install.html

In order to use the SDK you need to first execute the setsdkevn_unx script in the <OpenOffice.org>/basis3.1/sdk directory (/opt/openoffice.org/basis3.1/sdk for me). Before you execute this script, you need to locate all of the development tools for the language you will be using. Below is a list of the tools that the script prompts for and the locations of the tools on my machine.

<pre>
OpenOffice.org3 installation = /opt/openoffice.org3
GNU make 3.79.1 or higher = /usr/bin
C++ compiler (g++ 3.0.1 or higher) = /usr/bin
Zip = /usr/bin
Java = /usr/jdk/latest/
</pre>

Input the paths to your development tools when prompted.

You are now ready to use the OpenOffice SDK
}}

== Installation under Windows ==
{{Documentation/Windows|

You need a compiler out of the Microsoft Visual Studio family (other compilers like MinGW have turned out to be hard to configure for OOo on Windows).
The first thing after having installed the SDK is to launch the configureWindowsNT.bat and set all the necessary directories for proper use of the SDK.
If that has been done you have already installed everything, but *wait* one very important thing you should still know of:
Every time you want to run your own code or one of the SDK examples you need to launch the setsdkenv_Windows batch file from your command shell. The title of it should now be "Shell prepared for SDK". Happy coding, compiling and building now (I tell you it's easy from now on!).
GanescuCarmen describes some problems he encounter when trying SDK examples under Windows :
“I also use the 1.1 OO version.

I had a lots of problems.
Finally I succeeded to obtain the the header files, and in VC I needed some library to be included into project and some files(uno.idl) to be added to rdb files.
It was very hard to understand what it means registry(the rdb file not the Registry itself).

I was expecting to register something in Registry but it wasn't like this.
And with the service manager I had some problems, with the port, because the connection with 8100 port was not done.
I had to modify a file and to add some code for 8100 port.

But I did it and it works now.”
}}

== Installing with the free MS Visual C++ Toolkit 2003 ==
{{Documentation/HelpNeeded|This section needs help for update because '''MS Visual C++ Toolkit 2003''' seems no more available. Please have a look at Microsoft for the free Visual C++ tools at the moment.}}
I have installed DevCpp to have a make executable file.
I have downloaded the free Visual C++ Toolkit 2003 here :
http://www.microsoft.com/downloads/details.aspx?FamilyID=272be09d-40bb-49fd-9cb0-4bfa122fa91b&displaylang=en

and then I have installed it. '''(This link is broken.)'''

I launch first C:\openoffice\OpenOffice.org2.0_SDK\configureWindowsNT.bat
which asks any questions :
<pre>
set OO_SDK_HOME=C:\openoffice\OpenOffice.org2.0_SDK
set OFFICE_HOME=C:\Program Files\OpenOffice.org 2.0
set OO_SDK_MAKE_HOME=C:\Dev-C++\Bin
set OO_SDK_CPP_HOME=C:\Program Files\Microsoft Visual C++ Toolkit 2003\Bin
set OO_SDK_JAVA_HOME=C:\Program Files\Java\jdk1.5.0_03
</pre>

and I am ready to launch setsdkenv_windows.bat

I have modified the following file :
C:\openoffice\OpenOffice.org2.0_SDK\examples\DevelopersGuide\ProfUNO\CppBinding\office_connect.cxx
to change the port accordingly to what OOo is listening.

I have modified the makefile :
added :
<pre>
CC_INCLUDES = -I"C:\Program Files\Microsoft Visual C++ Toolkit 2003\include" \
-I"C:\openoffice\OpenOffice.org2.0_SDK\include"
</pre>

and added libraries too :

<pre>
$(OUT_BIN)/%$(EXE_EXT) : $(SAMPLE_OBJ_OUT)/%.$(OBJ_EXT)
-$(MKDIR) $(subst /,$(PS),$(@D))
-$(MKDIR) $(subst /,$(PS),$(SAMPLE_GEN_OUT))
ifeq "$(OS)" "WIN"
$(LINK) $(EXE_LINK_FLAGS) /OUT:$@ /MAP:$(SAMPLE_GEN_OUT)/$(subst $(EXE_EXT),.map,$(@F)) \
$< $(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB)\
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libcp.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libc.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\oldnames.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\kernel32.lib"
else
$(LINK) $(EXE_LINK_FLAGS) $(LINK_LIBS) -o $@ $< \
$(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB) $(STDC++LIB)
endif
</pre>
I suppose there is a more straightforward way to add these libraries with adding the corresponding include path but I am unable to do that with VC++.

I find a solution of the previous problem three weeks later. My problem comes in fact from a bug in setsdkenv_windows.bat. A little correction in the file setsdkenv_windows.bat makes it possible to avoid the makefile modifications :
Put :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "C:\Program Files\Microsoft Visual C++ Toolkit 2003\VCVARS32.bat"
</pre>

instead of :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "%OO_SDK_CPP_HOME%\VCVARS32.bat"
</pre>
I think
<pre>
%OO_SDK_CPP_HOME%\..\VCVARS32.bat
</pre>
could work too (but not checked). You can also move vcvars32.bat in %OO_SDK_CPP_HOME%
("C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin" for me).

== Other Windows Installations descriptions ==

You can find in [http://www.oooforum.org/forum/viewtopic.phtml?t=23772 OOoForum] a post entitled Guide for develop OpenOffice apps with VC++ .net (by [[CppSDKAuthors|LarsB]])

1.Download and install OpenOffice.

2.Download and install OpenOffice SDK

3.Create a new folder inludecpp in <oo_sdk_path>

4.Open Dos console change directory to <oo_sdk_path>\windows\bin

4.1 run cppumaker with followig paramerers
<pre>
cppumaker -BUCR -O <oo_sdk_path>\includecpp <office_programm_dir>\types.rdb
</pre>
or better with
<pre>
cppumaker -Gc -BUCR -O<includes_path> <ooffice_path>\URE\misc\types.rdb <ooffice_path>\Basis\program\offapi.rdb
</pre>
in recent versions.

(Attention: If you recieve a init error, copy types.rdb into the <oo_sdk_path>\windows\bin folder!)
After that all hpp and hdl files should be created in <oo_sdk_path>\includecpp

5.Open Visual Studio and create a new Win32 Console Application.
Applay the following changes to your project.

5.1. Tools ->Options->Projects->VC++ Directories -> Include Files
Add \include directory and <oo_sdk_path>\includecpp

5.2. Tools ->Options->Projects->VC++ Directories -> Library files
Add <oo_sdk_path>\windows\lib directory

5.3. Tools ->Options->Projects->VC++ Directories -> Executable files
Add <office_programm_dir>\program directory (location where you installed the version of the OpenOffice)

5.4 Open the Project Settings

5.4.1 Change Configuration to all All Configurations (the combobox in the left corner of the window)

5.4.2 Add the additional libraries

Properties->Linker->ComandLine in the Additional Options tab the library files
isal.lib icppu.lib icppuhelper.lib isal.lib isalhelper.lib ireg.lib irmcxt.lib stlport_vc71.lib

6.(example) Add the DocumentLoader.cxx from the cpp examples of the sdk
and compile. The source should compile without errors.

INFO : If you got the following error have a look at the solution 2 postings above!
Up to now, with the steps above i got the following error, when i run the DocumentLoader example.
The error is thrown, when the prog execution reach the following line:

<pre>

Reference< XSimpleRegistry > xSimpleRegistry( ::cppu::createSimpleRegistry() );
</pre>

with error shown below :

<pre>
Error:
Window title: Microsoft Visual C++ Debug Library
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

If somebody has experience with this kind of error it will be nice if he could
post a solution. So that here is a complete little guide for OpenOffice with VC++ .NET

Regards
[[CppSDKAuthors|Lars]]

[[CppSDKAuthors|François]] has improved the complete procedure with remarks :
Following all the steps I (_francois_) encountered two problems

* first in point 4.4.2

But there I guess it's because the procedure was meant for SDK 2 and I'm using SDK 1.1
The stlport_vc71.lib which you must include is distributed with the SDK 2 in the SDK 1.1 stlport_vc7.lib
you just need to include the stlport_vc7.lib instead of stlport_vc71.lib

* second problem after successfuly compiling the DocumentLoader in Visual Studio I was getting the following error
Error:
<pre>
Window title: Microsoft Visual C++ Debug Libary
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

After going on debug in the visual studio I found the following line was responsible

<pre>
xSimpleRegistry->open( OUString( RTL_CONSTASCII_USTRINGPARAM("DocumentLoader.rdb") ), sal_True, sal_False );
</pre>

The DocumentLoader.rdb was missing ... I noticed that if I compiled the DocumentLoader exemples from command line with the makefile provided with the exemple a DocumentLoader.rdb was generated. I had a look at the Makefile I isolated the lines which seemed to generate the DocumentLoader.rdb into my Debug folder (or wherever your set your DocumentLoader.exe to be put by Visual Studio) in my Visual Studio project...

<pre>
regmerge c:\travail\DocumentLoader\debug\DocumentLoader.rdb / "C:\ooo\office\program\types.rdb"

regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c connector.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c remotebridge.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c bridgefac.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c uuresolver.uno.dll
</pre>

I launched all the above lines in the prompt shell and it worked I had my DocumentLoader.rdb in my Debug folder

I launched my exe file and it worked, great...

Now I guess I still need to figure out which *.uno.dll needs to be included for which functions used in the programm, but still it's a good start.
If anyone has any information about that (It may actualy be documented somewhere) don't hesitate)

== The Development Tools of the SDK ==

There are several development tools provided with the SDK : idlc, cppumaker, javamaker, rdbmaker, pkgchk, regcomp, regmerge, regview, xml2cmp, uno, and autodoc. You can find a short documentation on these tools at <OOo_SDK>/docs/tools.html and also in [[Documentation/DevGuide/WritingUNO/Required_Files|Developer's Guide]].

See also [[Compiler_versions_used_by_port_maintainers_and_release_engineers|Compiler versions used by port maintainers and release engineers]]

== One Cpp Example ==
If you want to check the Cpp examples, you have to launch first (as mentioned before)
{{Documentation/Linux|
<pre>
./setsdkenv_unix
</pre>
}}
in your shell and then
{{Documentation/Linux|
<pre>
<Ooo>/program/soffice "-accept=socket,host=localhost,port=8100;urp;StarOffice.ServiceManager"
</pre>
}}
For Openoffice.org 2.x, run instead:
{{Documentation/Linux|
<pre>
<Ooo>/program/soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager"
</pre>
}}
Now Openoffice.org is listening on UNO connections through the network (here from localhost only).
We are ready to compile our first example and to check if it works correctly. For that we go in
<OpenOffice.org1.1_SDK>/examples/cpp/DocumentLoader directory.
<pre>
make
</pre>
will compile the example, and
<pre>
make DocumentLoader.run
</pre>
will launch the example. This example only load a Ooowriter's file (test.sxw) provided with the SDK.

Bear in mind the easier way to construct the examples of the SDK is to use the makefiles provided. When you are a beginner with the SDK you always underestimate important steps : for example the registry step discussed later. I estimate to have understand something when I am able to construct it starting with nothing (but skills). In the case of SDK this will take me a long time (and probably will not be finished). Then I can give you an advice : if you want to start a project, begin with modifying an example of the SDK.

Other SDK's examples are discussed later, but you can have a look to :

*[[Counter_Example|Counter example]]

{{Template:Home_Page}}

= See also =
* [[FR/Documentation/Installation_du_SDK|French version of this chapter]].
* [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno|C++ and UNO tutorial]]
* [http://www.codeproject.com/KB/wtl/Wtl_OOo.aspx Prepare the OOo SDK]
* [http://www.oooforum.org/forum/viewtopic.phtml?t=79911&highlight= missing files in sdk]
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal

[[Category:Tutorial]]
[[Category:Cpp]]
[[Category:Uno]]

SDKInstallation

2014-07-07T22:56:07Z

Global667: /* Installation under Mac OS X (Intel processors) */ Add conclusion of the SDK test

{{Documentation/Banner}}
{{Documentation/NeedsRework}}
= How to install the SDK and compile the C++ examples =

For both Linux and Windows the following points are very important if you want to succeed in building C++ components and snippets:
* you need to have OpenOffice.org 1.1.0 or higher installed (SDK won't run without it)
* you need to install the SDK into a directory other than the one of the OOo application

== Installation under Mac OS X (Intel processors) ==
{{Documentation/OSX|
The text below describes the installation of the SDK 4.1 on Mac OS X 10.9.4 with Xcode 4.1.1. It would works for other configurations too.
* Install Xcode. You can get it from the Apple App Store. Perhaps you must be registered as Mac developer under http://www.developer.apple.com
* Install OpenOffice 4.1
* Install MacPorts from http://www.macports.org. Perhaps you need to customize the path. You need MacPorts to install Unix-like software needed by the SDK.
* Install the SDK from http://openoffice.apache.org/downloads.html (You need 4.1.0 for MacOS_x86-64)
* Test the SDK. Open a terminal and look for the SDK folder. Now type and run:
<pre>
cd <SDK_Folder>
./setsdkenv_unix
cd examples/cpp/DocumentLoader
make
soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager" & make DocumentLoader.run
</pre>
If everything went fine, you should see a new document, with the content of <SDK_Folder>/examples/cpp/DocumentLoader/test.odt.

Further informations see: http://www.openoffice.org/api/SDK/
}}

== Installation under LINUX ==
{{Documentation/Linux|
The text below describe the installation of the SDK 1.1.0 for OpenOffice.org1.1.0

The Software Development Kit (SDK) works on the top of an existing Openoffice.org installation because of using the same libraries. The SDK requires an Openoffice.org installation.
Even if you don't plan to use Java it is strongly recommended to install the JDK (1.4.1_01 or higher for OOo 1.1 SDK)
Of course a C++ compiler is needed (3.0.1 or higher). GNU make (3.79.1 or higher) is also essential.
When ready, launch :
<pre>
tar xzvf Ooo_1.1.0_LinuxIntel_sdk.tar.gz
</pre>

and go to the new created directory (in this example OpenOffice.org1.1_SDK) and launch the configure script which asks you relevant directories. We give here among others :
* where is your OpenOffice.org installed ? (for me /usr/lib/openoffice : noted <Ooo> later)
* Where is your Java SDK installed ? (for me /usr/java/j2sdk1.4.2_04)

Now you are ready to use the SDK. Every time you want to use it you have to launch the setsdkenv_unix script for environment variables. Automating this is not a problem under UNIX.

From now on, we will always note the SDK directory installation as : <OpenOffice.org1.1_SDK>. Please don't confuse with <Ooo> which is the openoffice.org /program/ directory.

You can find a little complement of this chapter in <OpenOffice.org1.1_SDK>/docs/install.html

The OOo2.0SDK installation is done also by launching the setsdkenv_unix script but asking more information :
<pre>
************************************************************************
*
* SDK environment is prepared for Linux
*
* SDK = /home/smoutou/openoffice.org2.0_sdk
* Office = /opt/openoffice.org2.0
* URE =
* Make = /usr/bin
* Zip = /usr/bin
* C++ Compiler = /usr/bin
* Java = /usr/java/j2sdk1.4.2_04
* Special Output directory = /home/smoutou
* Auto deployment = YES
*
************************************************************************

</pre>
}}

== Installation under Solaris ==
{{Documentation/Linux|
The text below describe the installation of the OpenOffic.org SDK 3.1 for OpenOffice.org3.1

The Software Development Kit (SDK) works on the top of an existing Openoffice.org installation because of using the same libraries. The SDK requires an Openoffice.org installation (default installation directory for Solaris is /opt/openoffice.org/ and /opt/openoffice.org3/)

Depending on which language you wish to use, you will need either:
The Java SDK which can be obtained [http://java.sun.com/javase/downloads/index.jsp here].
Or a C++ complier (g++ 3.0.1 or higher is recommended). As well as GNU make (3.79.1 or higher) is also essential.

First download the Solaris SDK from [http://download.openoffice.org/sdk/index.html here].

Now run the install script by typing the following command. This script will prompt you for a temporary directory where it will extract the installation package. Just press enter and the package will be extracted into the directory shown in brackets (in this case /var/tmp/unpack_openofficeorg). If you wish to extract the package into a separate directory, type in the full directory path at the prompt.

<pre>
# sh OOo-SDK_3.1.1_SolarisSparc_install_en-US.sh
Select the directory in which to save the unpacked files. [/var/tmp/unpack_openofficeorg]

File is being checked for errors ...
Unpacking ...
All files have been successfully unpacked.
</pre>

Now navigate into the packages directory under the unpacked installation directory that was just created.

<pre>
# cd /var/tmp/unpack_openofficeorg/packages
</pre>

Go ahead an install the SDK package using pfexec.

<pre>
# pfexec pkgadd -d .
</pre>

To check if the installation succeeded, attempt to navigate into the sdk directory under the OpenOffic.org basis directory.
<pre>
# cd /opt/openoffice.org/basis3.1/sdk
# ls
bin/ examples/ setsdkenv_unix.csh.in
classes/ idl/ setsdkenv_unix.sh.in
config.guess include/ settings/
config.sub index.html share/
configure.pl lib/
docs/ setsdkenv_unix
</pre>

Now you are ready to use the SDK. Every time you want to use it you have to launch the setsdkenv_unix script for environment variables. Automating this is not a problem under UNIX. You can find a little complement of this chapter in <OpenOffice.org1.1_SDK>/docs/install.html

In order to use the SDK you need to first execute the setsdkevn_unx script in the <OpenOffice.org>/basis3.1/sdk directory (/opt/openoffice.org/basis3.1/sdk for me). Before you execute this script, you need to locate all of the development tools for the language you will be using. Below is a list of the tools that the script prompts for and the locations of the tools on my machine.

<pre>
OpenOffice.org3 installation = /opt/openoffice.org3
GNU make 3.79.1 or higher = /usr/bin
C++ compiler (g++ 3.0.1 or higher) = /usr/bin
Zip = /usr/bin
Java = /usr/jdk/latest/
</pre>

Input the paths to your development tools when prompted.

You are now ready to use the OpenOffice SDK
}}

== Installation under Windows ==
{{Documentation/Windows|

You need a compiler out of the Microsoft Visual Studio family (other compilers like MinGW have turned out to be hard to configure for OOo on Windows).
The first thing after having installed the SDK is to launch the configureWindowsNT.bat and set all the necessary directories for proper use of the SDK.
If that has been done you have already installed everything, but *wait* one very important thing you should still know of:
Every time you want to run your own code or one of the SDK examples you need to launch the setsdkenv_Windows batch file from your command shell. The title of it should now be "Shell prepared for SDK". Happy coding, compiling and building now (I tell you it's easy from now on!).
GanescuCarmen describes some problems he encounter when trying SDK examples under Windows :
“I also use the 1.1 OO version.

I had a lots of problems.
Finally I succeeded to obtain the the header files, and in VC I needed some library to be included into project and some files(uno.idl) to be added to rdb files.
It was very hard to understand what it means registry(the rdb file not the Registry itself).

I was expecting to register something in Registry but it wasn't like this.
And with the service manager I had some problems, with the port, because the connection with 8100 port was not done.
I had to modify a file and to add some code for 8100 port.

But I did it and it works now.”
}}

== Installing with the free MS Visual C++ Toolkit 2003 ==
{{Documentation/HelpNeeded|This section needs help for update because '''MS Visual C++ Toolkit 2003''' seems no more available. Please have a look at Microsoft for the free Visual C++ tools at the moment.}}
I have installed DevCpp to have a make executable file.
I have downloaded the free Visual C++ Toolkit 2003 here :
http://www.microsoft.com/downloads/details.aspx?FamilyID=272be09d-40bb-49fd-9cb0-4bfa122fa91b&displaylang=en

and then I have installed it. '''(This link is broken.)'''

I launch first C:\openoffice\OpenOffice.org2.0_SDK\configureWindowsNT.bat
which asks any questions :
<pre>
set OO_SDK_HOME=C:\openoffice\OpenOffice.org2.0_SDK
set OFFICE_HOME=C:\Program Files\OpenOffice.org 2.0
set OO_SDK_MAKE_HOME=C:\Dev-C++\Bin
set OO_SDK_CPP_HOME=C:\Program Files\Microsoft Visual C++ Toolkit 2003\Bin
set OO_SDK_JAVA_HOME=C:\Program Files\Java\jdk1.5.0_03
</pre>

and I am ready to launch setsdkenv_windows.bat

I have modified the following file :
C:\openoffice\OpenOffice.org2.0_SDK\examples\DevelopersGuide\ProfUNO\CppBinding\office_connect.cxx
to change the port accordingly to what OOo is listening.

I have modified the makefile :
added :
<pre>
CC_INCLUDES = -I"C:\Program Files\Microsoft Visual C++ Toolkit 2003\include" \
-I"C:\openoffice\OpenOffice.org2.0_SDK\include"
</pre>

and added libraries too :

<pre>
$(OUT_BIN)/%$(EXE_EXT) : $(SAMPLE_OBJ_OUT)/%.$(OBJ_EXT)
-$(MKDIR) $(subst /,$(PS),$(@D))
-$(MKDIR) $(subst /,$(PS),$(SAMPLE_GEN_OUT))
ifeq "$(OS)" "WIN"
$(LINK) $(EXE_LINK_FLAGS) /OUT:$@ /MAP:$(SAMPLE_GEN_OUT)/$(subst $(EXE_EXT),.map,$(@F)) \
$< $(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB)\
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libcp.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libc.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\oldnames.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\kernel32.lib"
else
$(LINK) $(EXE_LINK_FLAGS) $(LINK_LIBS) -o $@ $< \
$(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB) $(STDC++LIB)
endif
</pre>
I suppose there is a more straightforward way to add these libraries with adding the corresponding include path but I am unable to do that with VC++.

I find a solution of the previous problem three weeks later. My problem comes in fact from a bug in setsdkenv_windows.bat. A little correction in the file setsdkenv_windows.bat makes it possible to avoid the makefile modifications :
Put :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "C:\Program Files\Microsoft Visual C++ Toolkit 2003\VCVARS32.bat"
</pre>

instead of :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "%OO_SDK_CPP_HOME%\VCVARS32.bat"
</pre>
I think
<pre>
%OO_SDK_CPP_HOME%\..\VCVARS32.bat
</pre>
could work too (but not checked). You can also move vcvars32.bat in %OO_SDK_CPP_HOME%
("C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin" for me).

== Other Windows Installations descriptions ==

You can find in [http://www.oooforum.org/forum/viewtopic.phtml?t=23772 OOoForum] a post entitled Guide for develop OpenOffice apps with VC++ .net (by [[CppSDKAuthors|LarsB]])

1.Download and install OpenOffice.

2.Download and install OpenOffice SDK

3.Create a new folder inludecpp in <oo_sdk_path>

4.Open Dos console change directory to <oo_sdk_path>\windows\bin

4.1 run cppumaker with followig paramerers
<pre>
cppumaker -BUCR -O <oo_sdk_path>\includecpp <office_programm_dir>\types.rdb
</pre>
or better with
<pre>
cppumaker -Gc -BUCR -O<includes_path> <ooffice_path>\URE\misc\types.rdb <ooffice_path>\Basis\program\offapi.rdb
</pre>
in recent versions.

(Attention: If you recieve a init error, copy types.rdb into the <oo_sdk_path>\windows\bin folder!)
After that all hpp and hdl files should be created in <oo_sdk_path>\includecpp

5.Open Visual Studio and create a new Win32 Console Application.
Applay the following changes to your project.

5.1. Tools ->Options->Projects->VC++ Directories -> Include Files
Add \include directory and <oo_sdk_path>\includecpp

5.2. Tools ->Options->Projects->VC++ Directories -> Library files
Add <oo_sdk_path>\windows\lib directory

5.3. Tools ->Options->Projects->VC++ Directories -> Executable files
Add <office_programm_dir>\program directory (location where you installed the version of the OpenOffice)

5.4 Open the Project Settings

5.4.1 Change Configuration to all All Configurations (the combobox in the left corner of the window)

5.4.2 Add the additional libraries

Properties->Linker->ComandLine in the Additional Options tab the library files
isal.lib icppu.lib icppuhelper.lib isal.lib isalhelper.lib ireg.lib irmcxt.lib stlport_vc71.lib

6.(example) Add the DocumentLoader.cxx from the cpp examples of the sdk
and compile. The source should compile without errors.

INFO : If you got the following error have a look at the solution 2 postings above!
Up to now, with the steps above i got the following error, when i run the DocumentLoader example.
The error is thrown, when the prog execution reach the following line:

<pre>

Reference< XSimpleRegistry > xSimpleRegistry( ::cppu::createSimpleRegistry() );
</pre>

with error shown below :

<pre>
Error:
Window title: Microsoft Visual C++ Debug Library
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

If somebody has experience with this kind of error it will be nice if he could
post a solution. So that here is a complete little guide for OpenOffice with VC++ .NET

Regards
[[CppSDKAuthors|Lars]]

[[CppSDKAuthors|François]] has improved the complete procedure with remarks :
Following all the steps I (_francois_) encountered two problems

* first in point 4.4.2

But there I guess it's because the procedure was meant for SDK 2 and I'm using SDK 1.1
The stlport_vc71.lib which you must include is distributed with the SDK 2 in the SDK 1.1 stlport_vc7.lib
you just need to include the stlport_vc7.lib instead of stlport_vc71.lib

* second problem after successfuly compiling the DocumentLoader in Visual Studio I was getting the following error
Error:
<pre>
Window title: Microsoft Visual C++ Debug Libary
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

After going on debug in the visual studio I found the following line was responsible

<pre>
xSimpleRegistry->open( OUString( RTL_CONSTASCII_USTRINGPARAM("DocumentLoader.rdb") ), sal_True, sal_False );
</pre>

The DocumentLoader.rdb was missing ... I noticed that if I compiled the DocumentLoader exemples from command line with the makefile provided with the exemple a DocumentLoader.rdb was generated. I had a look at the Makefile I isolated the lines which seemed to generate the DocumentLoader.rdb into my Debug folder (or wherever your set your DocumentLoader.exe to be put by Visual Studio) in my Visual Studio project...

<pre>
regmerge c:\travail\DocumentLoader\debug\DocumentLoader.rdb / "C:\ooo\office\program\types.rdb"

regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c connector.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c remotebridge.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c bridgefac.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c uuresolver.uno.dll
</pre>

I launched all the above lines in the prompt shell and it worked I had my DocumentLoader.rdb in my Debug folder

I launched my exe file and it worked, great...

Now I guess I still need to figure out which *.uno.dll needs to be included for which functions used in the programm, but still it's a good start.
If anyone has any information about that (It may actualy be documented somewhere) don't hesitate)

== The Development Tools of the SDK ==

There are several development tools provided with the SDK : idlc, cppumaker, javamaker, rdbmaker, pkgchk, regcomp, regmerge, regview, xml2cmp, uno, and autodoc. You can find a short documentation on these tools at <OOo_SDK>/docs/tools.html and also in [[Documentation/DevGuide/WritingUNO/Required_Files|Developer's Guide]].

See also [[Compiler_versions_used_by_port_maintainers_and_release_engineers|Compiler versions used by port maintainers and release engineers]]

== One Cpp Example ==
If you want to check the Cpp examples, you have to launch first (as mentioned before)
{{Documentation/Linux|
<pre>
./setsdkenv_unix
</pre>
}}
in your shell and then
{{Documentation/Linux|
<pre>
<Ooo>/program/soffice "-accept=socket,host=localhost,port=8100;urp;StarOffice.ServiceManager"
</pre>
}}
For Openoffice.org 2.x, run instead:
{{Documentation/Linux|
<pre>
<Ooo>/program/soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager"
</pre>
}}
Now Openoffice.org is listening on UNO connections through the network (here from localhost only).
We are ready to compile our first example and to check if it works correctly. For that we go in
<OpenOffice.org1.1_SDK>/examples/cpp/DocumentLoader directory.
<pre>
make
</pre>
will compile the example, and
<pre>
make DocumentLoader.run
</pre>
will launch the example. This example only load a Ooowriter's file (test.sxw) provided with the SDK.

Bear in mind the easier way to construct the examples of the SDK is to use the makefiles provided. When you are a beginner with the SDK you always underestimate important steps : for example the registry step discussed later. I estimate to have understand something when I am able to construct it starting with nothing (but skills). In the case of SDK this will take me a long time (and probably will not be finished). Then I can give you an advice : if you want to start a project, begin with modifying an example of the SDK.

Other SDK's examples are discussed later, but you can have a look to :

*[[Counter_Example|Counter example]]

{{Template:Home_Page}}

= See also =
* [[FR/Documentation/Installation_du_SDK|French version of this chapter]].
* [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno|C++ and UNO tutorial]]
* [http://www.codeproject.com/KB/wtl/Wtl_OOo.aspx Prepare the OOo SDK]
* [http://www.oooforum.org/forum/viewtopic.phtml?t=79911&highlight= missing files in sdk]
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal

[[Category:Tutorial]]
[[Category:Cpp]]
[[Category:Uno]]

SDKInstallation

2014-07-07T22:27:40Z

Global667: Undo revision 235357 by Global667 (talk) text was deleted don't know why

{{Documentation/Banner}}
{{Documentation/NeedsRework}}
= How to install the SDK and compile the C++ examples =

For both Linux and Windows the following points are very important if you want to succeed in building C++ components and snippets:
* you need to have OpenOffice.org 1.1.0 or higher installed (SDK won't run without it)
* you need to install the SDK into a directory other than the one of the OOo application

== Installation under Mac OS X (Intel processors) ==
{{Documentation/OSX|
The text below describes the installation of the SDK 4.1 on Mac OS X 10.9.4 with Xcode 4.1.1. It would works for other configurations too.
* Install Xcode. You can get it from the Apple App Store. Perhaps you must be registered as Mac developer under http://www.developer.apple.com
* Install OpenOffice 4.1
* Install MacPorts from http://www.macports.org. Perhaps you need to customize the path. You need MacPorts to install Unix-like software needed by the SDK.
* Install the SDK from http://openoffice.apache.org/downloads.html (You need 4.1.0 for MacOS_x86-64)
* Test the SDK. Open a terminal and look for the SDK folder. Now type and run:
<pre>
cd <SDK_Folder>
./setsdkenv_unix
cd examples/cpp/DocumentLoader
make
soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager" & make DocumentLoader.run
</pre>
Further informations see: http://www.openoffice.org/api/SDK/
}}

== Installation under LINUX ==
{{Documentation/Linux|
The text below describe the installation of the SDK 1.1.0 for OpenOffice.org1.1.0

The Software Development Kit (SDK) works on the top of an existing Openoffice.org installation because of using the same libraries. The SDK requires an Openoffice.org installation.
Even if you don't plan to use Java it is strongly recommended to install the JDK (1.4.1_01 or higher for OOo 1.1 SDK)
Of course a C++ compiler is needed (3.0.1 or higher). GNU make (3.79.1 or higher) is also essential.
When ready, launch :
<pre>
tar xzvf Ooo_1.1.0_LinuxIntel_sdk.tar.gz
</pre>

and go to the new created directory (in this example OpenOffice.org1.1_SDK) and launch the configure script which asks you relevant directories. We give here among others :
* where is your OpenOffice.org installed ? (for me /usr/lib/openoffice : noted <Ooo> later)
* Where is your Java SDK installed ? (for me /usr/java/j2sdk1.4.2_04)

Now you are ready to use the SDK. Every time you want to use it you have to launch the setsdkenv_unix script for environment variables. Automating this is not a problem under UNIX.

From now on, we will always note the SDK directory installation as : <OpenOffice.org1.1_SDK>. Please don't confuse with <Ooo> which is the openoffice.org /program/ directory.

You can find a little complement of this chapter in <OpenOffice.org1.1_SDK>/docs/install.html

The OOo2.0SDK installation is done also by launching the setsdkenv_unix script but asking more information :
<pre>
************************************************************************
*
* SDK environment is prepared for Linux
*
* SDK = /home/smoutou/openoffice.org2.0_sdk
* Office = /opt/openoffice.org2.0
* URE =
* Make = /usr/bin
* Zip = /usr/bin
* C++ Compiler = /usr/bin
* Java = /usr/java/j2sdk1.4.2_04
* Special Output directory = /home/smoutou
* Auto deployment = YES
*
************************************************************************

</pre>
}}

== Installation under Solaris ==
{{Documentation/Linux|
The text below describe the installation of the OpenOffic.org SDK 3.1 for OpenOffice.org3.1

The Software Development Kit (SDK) works on the top of an existing Openoffice.org installation because of using the same libraries. The SDK requires an Openoffice.org installation (default installation directory for Solaris is /opt/openoffice.org/ and /opt/openoffice.org3/)

Depending on which language you wish to use, you will need either:
The Java SDK which can be obtained [http://java.sun.com/javase/downloads/index.jsp here].
Or a C++ complier (g++ 3.0.1 or higher is recommended). As well as GNU make (3.79.1 or higher) is also essential.

First download the Solaris SDK from [http://download.openoffice.org/sdk/index.html here].

Now run the install script by typing the following command. This script will prompt you for a temporary directory where it will extract the installation package. Just press enter and the package will be extracted into the directory shown in brackets (in this case /var/tmp/unpack_openofficeorg). If you wish to extract the package into a separate directory, type in the full directory path at the prompt.

<pre>
# sh OOo-SDK_3.1.1_SolarisSparc_install_en-US.sh
Select the directory in which to save the unpacked files. [/var/tmp/unpack_openofficeorg]

File is being checked for errors ...
Unpacking ...
All files have been successfully unpacked.
</pre>

Now navigate into the packages directory under the unpacked installation directory that was just created.

<pre>
# cd /var/tmp/unpack_openofficeorg/packages
</pre>

Go ahead an install the SDK package using pfexec.

<pre>
# pfexec pkgadd -d .
</pre>

To check if the installation succeeded, attempt to navigate into the sdk directory under the OpenOffic.org basis directory.
<pre>
# cd /opt/openoffice.org/basis3.1/sdk
# ls
bin/ examples/ setsdkenv_unix.csh.in
classes/ idl/ setsdkenv_unix.sh.in
config.guess include/ settings/
config.sub index.html share/
configure.pl lib/
docs/ setsdkenv_unix
</pre>

Now you are ready to use the SDK. Every time you want to use it you have to launch the setsdkenv_unix script for environment variables. Automating this is not a problem under UNIX. You can find a little complement of this chapter in <OpenOffice.org1.1_SDK>/docs/install.html

In order to use the SDK you need to first execute the setsdkevn_unx script in the <OpenOffice.org>/basis3.1/sdk directory (/opt/openoffice.org/basis3.1/sdk for me). Before you execute this script, you need to locate all of the development tools for the language you will be using. Below is a list of the tools that the script prompts for and the locations of the tools on my machine.

<pre>
OpenOffice.org3 installation = /opt/openoffice.org3
GNU make 3.79.1 or higher = /usr/bin
C++ compiler (g++ 3.0.1 or higher) = /usr/bin
Zip = /usr/bin
Java = /usr/jdk/latest/
</pre>

Input the paths to your development tools when prompted.

You are now ready to use the OpenOffice SDK
}}

== Installation under Windows ==
{{Documentation/Windows|

You need a compiler out of the Microsoft Visual Studio family (other compilers like MinGW have turned out to be hard to configure for OOo on Windows).
The first thing after having installed the SDK is to launch the configureWindowsNT.bat and set all the necessary directories for proper use of the SDK.
If that has been done you have already installed everything, but *wait* one very important thing you should still know of:
Every time you want to run your own code or one of the SDK examples you need to launch the setsdkenv_Windows batch file from your command shell. The title of it should now be "Shell prepared for SDK". Happy coding, compiling and building now (I tell you it's easy from now on!).
GanescuCarmen describes some problems he encounter when trying SDK examples under Windows :
“I also use the 1.1 OO version.

I had a lots of problems.
Finally I succeeded to obtain the the header files, and in VC I needed some library to be included into project and some files(uno.idl) to be added to rdb files.
It was very hard to understand what it means registry(the rdb file not the Registry itself).

I was expecting to register something in Registry but it wasn't like this.
And with the service manager I had some problems, with the port, because the connection with 8100 port was not done.
I had to modify a file and to add some code for 8100 port.

But I did it and it works now.”
}}

== Installing with the free MS Visual C++ Toolkit 2003 ==
{{Documentation/HelpNeeded|This section needs help for update because '''MS Visual C++ Toolkit 2003''' seems no more available. Please have a look at Microsoft for the free Visual C++ tools at the moment.}}
I have installed DevCpp to have a make executable file.
I have downloaded the free Visual C++ Toolkit 2003 here :
http://www.microsoft.com/downloads/details.aspx?FamilyID=272be09d-40bb-49fd-9cb0-4bfa122fa91b&displaylang=en

and then I have installed it. '''(This link is broken.)'''

I launch first C:\openoffice\OpenOffice.org2.0_SDK\configureWindowsNT.bat
which asks any questions :
<pre>
set OO_SDK_HOME=C:\openoffice\OpenOffice.org2.0_SDK
set OFFICE_HOME=C:\Program Files\OpenOffice.org 2.0
set OO_SDK_MAKE_HOME=C:\Dev-C++\Bin
set OO_SDK_CPP_HOME=C:\Program Files\Microsoft Visual C++ Toolkit 2003\Bin
set OO_SDK_JAVA_HOME=C:\Program Files\Java\jdk1.5.0_03
</pre>

and I am ready to launch setsdkenv_windows.bat

I have modified the following file :
C:\openoffice\OpenOffice.org2.0_SDK\examples\DevelopersGuide\ProfUNO\CppBinding\office_connect.cxx
to change the port accordingly to what OOo is listening.

I have modified the makefile :
added :
<pre>
CC_INCLUDES = -I"C:\Program Files\Microsoft Visual C++ Toolkit 2003\include" \
-I"C:\openoffice\OpenOffice.org2.0_SDK\include"
</pre>

and added libraries too :

<pre>
$(OUT_BIN)/%$(EXE_EXT) : $(SAMPLE_OBJ_OUT)/%.$(OBJ_EXT)
-$(MKDIR) $(subst /,$(PS),$(@D))
-$(MKDIR) $(subst /,$(PS),$(SAMPLE_GEN_OUT))
ifeq "$(OS)" "WIN"
$(LINK) $(EXE_LINK_FLAGS) /OUT:$@ /MAP:$(SAMPLE_GEN_OUT)/$(subst $(EXE_EXT),.map,$(@F)) \
$< $(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB)\
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libcp.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libc.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\oldnames.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\kernel32.lib"
else
$(LINK) $(EXE_LINK_FLAGS) $(LINK_LIBS) -o $@ $< \
$(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB) $(STDC++LIB)
endif
</pre>
I suppose there is a more straightforward way to add these libraries with adding the corresponding include path but I am unable to do that with VC++.

I find a solution of the previous problem three weeks later. My problem comes in fact from a bug in setsdkenv_windows.bat. A little correction in the file setsdkenv_windows.bat makes it possible to avoid the makefile modifications :
Put :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "C:\Program Files\Microsoft Visual C++ Toolkit 2003\VCVARS32.bat"
</pre>

instead of :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "%OO_SDK_CPP_HOME%\VCVARS32.bat"
</pre>
I think
<pre>
%OO_SDK_CPP_HOME%\..\VCVARS32.bat
</pre>
could work too (but not checked). You can also move vcvars32.bat in %OO_SDK_CPP_HOME%
("C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin" for me).

== Other Windows Installations descriptions ==

You can find in [http://www.oooforum.org/forum/viewtopic.phtml?t=23772 OOoForum] a post entitled Guide for develop OpenOffice apps with VC++ .net (by [[CppSDKAuthors|LarsB]])

1.Download and install OpenOffice.

2.Download and install OpenOffice SDK

3.Create a new folder inludecpp in <oo_sdk_path>

4.Open Dos console change directory to <oo_sdk_path>\windows\bin

4.1 run cppumaker with followig paramerers
<pre>
cppumaker -BUCR -O <oo_sdk_path>\includecpp <office_programm_dir>\types.rdb
</pre>
or better with
<pre>
cppumaker -Gc -BUCR -O<includes_path> <ooffice_path>\URE\misc\types.rdb <ooffice_path>\Basis\program\offapi.rdb
</pre>
in recent versions.

(Attention: If you recieve a init error, copy types.rdb into the <oo_sdk_path>\windows\bin folder!)
After that all hpp and hdl files should be created in <oo_sdk_path>\includecpp

5.Open Visual Studio and create a new Win32 Console Application.
Applay the following changes to your project.

5.1. Tools ->Options->Projects->VC++ Directories -> Include Files
Add \include directory and <oo_sdk_path>\includecpp

5.2. Tools ->Options->Projects->VC++ Directories -> Library files
Add <oo_sdk_path>\windows\lib directory

5.3. Tools ->Options->Projects->VC++ Directories -> Executable files
Add <office_programm_dir>\program directory (location where you installed the version of the OpenOffice)

5.4 Open the Project Settings

5.4.1 Change Configuration to all All Configurations (the combobox in the left corner of the window)

5.4.2 Add the additional libraries

Properties->Linker->ComandLine in the Additional Options tab the library files
isal.lib icppu.lib icppuhelper.lib isal.lib isalhelper.lib ireg.lib irmcxt.lib stlport_vc71.lib

6.(example) Add the DocumentLoader.cxx from the cpp examples of the sdk
and compile. The source should compile without errors.

INFO : If you got the following error have a look at the solution 2 postings above!
Up to now, with the steps above i got the following error, when i run the DocumentLoader example.
The error is thrown, when the prog execution reach the following line:

<pre>

Reference< XSimpleRegistry > xSimpleRegistry( ::cppu::createSimpleRegistry() );
</pre>

with error shown below :

<pre>
Error:
Window title: Microsoft Visual C++ Debug Library
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

If somebody has experience with this kind of error it will be nice if he could
post a solution. So that here is a complete little guide for OpenOffice with VC++ .NET

Regards
[[CppSDKAuthors|Lars]]

[[CppSDKAuthors|François]] has improved the complete procedure with remarks :
Following all the steps I (_francois_) encountered two problems

* first in point 4.4.2

But there I guess it's because the procedure was meant for SDK 2 and I'm using SDK 1.1
The stlport_vc71.lib which you must include is distributed with the SDK 2 in the SDK 1.1 stlport_vc7.lib
you just need to include the stlport_vc7.lib instead of stlport_vc71.lib

* second problem after successfuly compiling the DocumentLoader in Visual Studio I was getting the following error
Error:
<pre>
Window title: Microsoft Visual C++ Debug Libary
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

After going on debug in the visual studio I found the following line was responsible

<pre>
xSimpleRegistry->open( OUString( RTL_CONSTASCII_USTRINGPARAM("DocumentLoader.rdb") ), sal_True, sal_False );
</pre>

The DocumentLoader.rdb was missing ... I noticed that if I compiled the DocumentLoader exemples from command line with the makefile provided with the exemple a DocumentLoader.rdb was generated. I had a look at the Makefile I isolated the lines which seemed to generate the DocumentLoader.rdb into my Debug folder (or wherever your set your DocumentLoader.exe to be put by Visual Studio) in my Visual Studio project...

<pre>
regmerge c:\travail\DocumentLoader\debug\DocumentLoader.rdb / "C:\ooo\office\program\types.rdb"

regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c connector.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c remotebridge.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c bridgefac.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c uuresolver.uno.dll
</pre>

I launched all the above lines in the prompt shell and it worked I had my DocumentLoader.rdb in my Debug folder

I launched my exe file and it worked, great...

Now I guess I still need to figure out which *.uno.dll needs to be included for which functions used in the programm, but still it's a good start.
If anyone has any information about that (It may actualy be documented somewhere) don't hesitate)

== The Development Tools of the SDK ==

There are several development tools provided with the SDK : idlc, cppumaker, javamaker, rdbmaker, pkgchk, regcomp, regmerge, regview, xml2cmp, uno, and autodoc. You can find a short documentation on these tools at <OOo_SDK>/docs/tools.html and also in [[Documentation/DevGuide/WritingUNO/Required_Files|Developer's Guide]].

See also [[Compiler_versions_used_by_port_maintainers_and_release_engineers|Compiler versions used by port maintainers and release engineers]]

== One Cpp Example ==
If you want to check the Cpp examples, you have to launch first (as mentioned before)
{{Documentation/Linux|
<pre>
./setsdkenv_unix
</pre>
}}
in your shell and then
{{Documentation/Linux|
<pre>
<Ooo>/program/soffice "-accept=socket,host=localhost,port=8100;urp;StarOffice.ServiceManager"
</pre>
}}
For Openoffice.org 2.x, run instead:
{{Documentation/Linux|
<pre>
<Ooo>/program/soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager"
</pre>
}}
Now Openoffice.org is listening on UNO connections through the network (here from localhost only).
We are ready to compile our first example and to check if it works correctly. For that we go in
<OpenOffice.org1.1_SDK>/examples/cpp/DocumentLoader directory.
<pre>
make
</pre>
will compile the example, and
<pre>
make DocumentLoader.run
</pre>
will launch the example. This example only load a Ooowriter's file (test.sxw) provided with the SDK.

Bear in mind the easier way to construct the examples of the SDK is to use the makefiles provided. When you are a beginner with the SDK you always underestimate important steps : for example the registry step discussed later. I estimate to have understand something when I am able to construct it starting with nothing (but skills). In the case of SDK this will take me a long time (and probably will not be finished). Then I can give you an advice : if you want to start a project, begin with modifying an example of the SDK.

Other SDK's examples are discussed later, but you can have a look to :

*[[Counter_Example|Counter example]]

{{Template:Home_Page}}

= See also =
* [[FR/Documentation/Installation_du_SDK|French version of this chapter]].
* [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno|C++ and UNO tutorial]]
* [http://www.codeproject.com/KB/wtl/Wtl_OOo.aspx Prepare the OOo SDK]
* [http://www.oooforum.org/forum/viewtopic.phtml?t=79911&highlight= missing files in sdk]
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal

[[Category:Tutorial]]
[[Category:Cpp]]
[[Category:Uno]]

SDKInstallation

2014-07-07T22:22:58Z

Global667: /* Installation under Mac OS X (Intel processors) */ Spelling, add link

{{Documentation/Banner}}
{{Documentation/NeedsRework}}
= How to install the SDK and compile the C++ examples =

For both Linux and Windows the following points are very important if you want to succeed in building C++ components and snippets:
* you need to have OpenOffice.org 1.1.0 or higher installed (SDK won't run without it)
* you need to install the SDK into a directory other than the one of the OOo application

== Installation under LINUX ==
{{Documentation/Linux|
The text below describe the installation of the SDK 1.1.0 for OpenOffice.org1.1.0

The Software Development Kit (SDK) works on the top of an existing Openoffice.org installation because of using the same libraries. The SDK requires an Openoffice.org installation.
Even if you don't plan to use Java it is strongly recommended to install the JDK (1.4.1_01 or higher for OOo 1.1 SDK)
Of course a C++ compiler is needed (3.0.1 or higher). GNU make (3.79.1 or higher) is also essential.
When ready, launch :
<pre>
tar xzvf Ooo_1.1.0_LinuxIntel_sdk.tar.gz
</pre>

and go to the new created directory (in this example OpenOffice.org1.1_SDK) and launch the configure script which asks you relevant directories. We give here among others :
* where is your OpenOffice.org installed ? (for me /usr/lib/openoffice : noted <Ooo> later)
* Where is your Java SDK installed ? (for me /usr/java/j2sdk1.4.2_04)

Now you are ready to use the SDK. Every time you want to use it you have to launch the setsdkenv_unix script for environment variables. Automating this is not a problem under UNIX.

From now on, we will always note the SDK directory installation as : <OpenOffice.org1.1_SDK>. Please don't confuse with <Ooo> which is the openoffice.org /program/ directory.

You can find a little complement of this chapter in <OpenOffice.org1.1_SDK>/docs/install.html

The OOo2.0SDK installation is done also by launching the setsdkenv_unix script but asking more information :
<pre>
************************************************************************
*
* SDK environment is prepared for Linux
*
* SDK = /home/smoutou/openoffice.org2.0_sdk
* Office = /opt/openoffice.org2.0
* URE =
* Make = /usr/bin
* Zip = /usr/bin
* C++ Compiler = /usr/bin
* Java = /usr/java/j2sdk1.4.2_04
* Special Output directory = /home/smoutou
* Auto deployment = YES
*
************************************************************************

</pre>
}}

== Installation under Solaris ==
{{Documentation/Linux|
The text below describe the installation of the OpenOffic.org SDK 3.1 for OpenOffice.org3.1

The Software Development Kit (SDK) works on the top of an existing Openoffice.org installation because of using the same libraries. The SDK requires an Openoffice.org installation (default installation directory for Solaris is /opt/openoffice.org/ and /opt/openoffice.org3/)

Depending on which language you wish to use, you will need either:
The Java SDK which can be obtained [http://java.sun.com/javase/downloads/index.jsp here].
Or a C++ complier (g++ 3.0.1 or higher is recommended). As well as GNU make (3.79.1 or higher) is also essential.

First download the Solaris SDK from [http://download.openoffice.org/sdk/index.html here].

Now run the install script by typing the following command. This script will prompt you for a temporary directory where it will extract the installation package. Just press enter and the package will be extracted into the directory shown in brackets (in this case /var/tmp/unpack_openofficeorg). If you wish to extract the package into a separate directory, type in the full directory path at the prompt.

<pre>
# sh OOo-SDK_3.1.1_SolarisSparc_install_en-US.sh
Select the directory in which to save the unpacked files. [/var/tmp/unpack_openofficeorg]

File is being checked for errors ...
Unpacking ...
All files have been successfully unpacked.
</pre>

Now navigate into the packages directory under the unpacked installation directory that was just created.

<pre>
# cd /var/tmp/unpack_openofficeorg/packages
</pre>

Go ahead an install the SDK package using pfexec.

<pre>
# pfexec pkgadd -d .
</pre>

To check if the installation succeeded, attempt to navigate into the sdk directory under the OpenOffic.org basis directory.
<pre>
# cd /opt/openoffice.org/basis3.1/sdk
# ls
bin/ examples/ setsdkenv_unix.csh.in
classes/ idl/ setsdkenv_unix.sh.in
config.guess include/ settings/
config.sub index.html share/
configure.pl lib/
docs/ setsdkenv_unix
</pre>

Now you are ready to use the SDK. Every time you want to use it you have to launch the setsdkenv_unix script for environment variables. Automating this is not a problem under UNIX. You can find a little complement of this chapter in <OpenOffice.org1.1_SDK>/docs/install.html

In order to use the SDK you need to first execute the setsdkevn_unx script in the <OpenOffice.org>/basis3.1/sdk directory (/opt/openoffice.org/basis3.1/sdk for me). Before you execute this script, you need to locate all of the development tools for the language you will be using. Below is a list of the tools that the script prompts for and the locations of the tools on my machine.

<pre>
OpenOffice.org3 installation = /opt/openoffice.org3
GNU make 3.79.1 or higher = /usr/bin
C++ compiler (g++ 3.0.1 or higher) = /usr/bin
Zip = /usr/bin
Java = /usr/jdk/latest/
</pre>

Input the paths to your development tools when prompted.

You are now ready to use the OpenOffice SDK
}}

== Installation under Windows ==
{{Documentation/Windows|

You need a compiler out of the Microsoft Visual Studio family (other compilers like MinGW have turned out to be hard to configure for OOo on Windows).
The first thing after having installed the SDK is to launch the configureWindowsNT.bat and set all the necessary directories for proper use of the SDK.
If that has been done you have already installed everything, but *wait* one very important thing you should still know of:
Every time you want to run your own code or one of the SDK examples you need to launch the setsdkenv_Windows batch file from your command shell. The title of it should now be "Shell prepared for SDK". Happy coding, compiling and building now (I tell you it's easy from now on!).
GanescuCarmen describes some problems he encounter when trying SDK examples under Windows :
“I also use the 1.1 OO version.

I had a lots of problems.
Finally I succeeded to obtain the the header files, and in VC I needed some library to be included into project and some files(uno.idl) to be added to rdb files.
It was very hard to understand what it means registry(the rdb file not the Registry itself).

I was expecting to register something in Registry but it wasn't like this.
And with the service manager I had some problems, with the port, because the connection with 8100 port was not done.
I had to modify a file and to add some code for 8100 port.

But I did it and it works now.”
}}

== Installing with the free MS Visual C++ Toolkit 2003 ==
{{Documentation/HelpNeeded|This section needs help for update because '''MS Visual C++ Toolkit 2003''' seems no more available. Please have a look at Microsoft for the free Visual C++ tools at the moment.}}
I have installed DevCpp to have a make executable file.
I have downloaded the free Visual C++ Toolkit 2003 here :
http://www.microsoft.com/downloads/details.aspx?FamilyID=272be09d-40bb-49fd-9cb0-4bfa122fa91b&displaylang=en

and then I have installed it. '''(This link is broken.)'''

I launch first C:\openoffice\OpenOffice.org2.0_SDK\configureWindowsNT.bat
which asks any questions :
<pre>
set OO_SDK_HOME=C:\openoffice\OpenOffice.org2.0_SDK
set OFFICE_HOME=C:\Program Files\OpenOffice.org 2.0
set OO_SDK_MAKE_HOME=C:\Dev-C++\Bin
set OO_SDK_CPP_HOME=C:\Program Files\Microsoft Visual C++ Toolkit 2003\Bin
set OO_SDK_JAVA_HOME=C:\Program Files\Java\jdk1.5.0_03
</pre>

and I am ready to launch setsdkenv_windows.bat

I have modified the following file :
C:\openoffice\OpenOffice.org2.0_SDK\examples\DevelopersGuide\ProfUNO\CppBinding\office_connect.cxx
to change the port accordingly to what OOo is listening.

I have modified the makefile :
added :
<pre>
CC_INCLUDES = -I"C:\Program Files\Microsoft Visual C++ Toolkit 2003\include" \
-I"C:\openoffice\OpenOffice.org2.0_SDK\include"
</pre>

and added libraries too :

<pre>
$(OUT_BIN)/%$(EXE_EXT) : $(SAMPLE_OBJ_OUT)/%.$(OBJ_EXT)
-$(MKDIR) $(subst /,$(PS),$(@D))
-$(MKDIR) $(subst /,$(PS),$(SAMPLE_GEN_OUT))
ifeq "$(OS)" "WIN"
$(LINK) $(EXE_LINK_FLAGS) /OUT:$@ /MAP:$(SAMPLE_GEN_OUT)/$(subst $(EXE_EXT),.map,$(@F)) \
$< $(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB)\
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libcp.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libc.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\oldnames.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\kernel32.lib"
else
$(LINK) $(EXE_LINK_FLAGS) $(LINK_LIBS) -o $@ $< \
$(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB) $(STDC++LIB)
endif
</pre>
I suppose there is a more straightforward way to add these libraries with adding the corresponding include path but I am unable to do that with VC++.

I find a solution of the previous problem three weeks later. My problem comes in fact from a bug in setsdkenv_windows.bat. A little correction in the file setsdkenv_windows.bat makes it possible to avoid the makefile modifications :
Put :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "C:\Program Files\Microsoft Visual C++ Toolkit 2003\VCVARS32.bat"
</pre>

instead of :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "%OO_SDK_CPP_HOME%\VCVARS32.bat"
</pre>
I think
<pre>
%OO_SDK_CPP_HOME%\..\VCVARS32.bat
</pre>
could work too (but not checked). You can also move vcvars32.bat in %OO_SDK_CPP_HOME%
("C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin" for me).

== Other Windows Installations descriptions ==

You can find in [http://www.oooforum.org/forum/viewtopic.phtml?t=23772 OOoForum] a post entitled Guide for develop OpenOffice apps with VC++ .net (by [[CppSDKAuthors|LarsB]])

1.Download and install OpenOffice.

2.Download and install OpenOffice SDK

3.Create a new folder inludecpp in <oo_sdk_path>

4.Open Dos console change directory to <oo_sdk_path>\windows\bin

4.1 run cppumaker with followig paramerers
<pre>
cppumaker -BUCR -O <oo_sdk_path>\includecpp <office_programm_dir>\types.rdb
</pre>
or better with
<pre>
cppumaker -Gc -BUCR -O<includes_path> <ooffice_path>\URE\misc\types.rdb <ooffice_path>\Basis\program\offapi.rdb
</pre>
in recent versions.

(Attention: If you recieve a init error, copy types.rdb into the <oo_sdk_path>\windows\bin folder!)
After that all hpp and hdl files should be created in <oo_sdk_path>\includecpp

5.Open Visual Studio and create a new Win32 Console Application.
Applay the following changes to your project.

5.1. Tools ->Options->Projects->VC++ Directories -> Include Files
Add \include directory and <oo_sdk_path>\includecpp

5.2. Tools ->Options->Projects->VC++ Directories -> Library files
Add <oo_sdk_path>\windows\lib directory

5.3. Tools ->Options->Projects->VC++ Directories -> Executable files
Add <office_programm_dir>\program directory (location where you installed the version of the OpenOffice)

5.4 Open the Project Settings

5.4.1 Change Configuration to all All Configurations (the combobox in the left corner of the window)

5.4.2 Add the additional libraries

Properties->Linker->ComandLine in the Additional Options tab the library files
isal.lib icppu.lib icppuhelper.lib isal.lib isalhelper.lib ireg.lib irmcxt.lib stlport_vc71.lib

6.(example) Add the DocumentLoader.cxx from the cpp examples of the sdk
and compile. The source should compile without errors.

INFO : If you got the following error have a look at the solution 2 postings above!
Up to now, with the steps above i got the following error, when i run the DocumentLoader example.
The error is thrown, when the prog execution reach the following line:

<pre>

Reference< XSimpleRegistry > xSimpleRegistry( ::cppu::createSimpleRegistry() );
</pre>

with error shown below :

<pre>
Error:
Window title: Microsoft Visual C++ Debug Library
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

If somebody has experience with this kind of error it will be nice if he could
post a solution. So that here is a complete little guide for OpenOffice with VC++ .NET

Regards
[[CppSDKAuthors|Lars]]

[[CppSDKAuthors|François]] has improved the complete procedure with remarks :
Following all the steps I (_francois_) encountered two problems

* first in point 4.4.2

But there I guess it's because the procedure was meant for SDK 2 and I'm using SDK 1.1
The stlport_vc71.lib which you must include is distributed with the SDK 2 in the SDK 1.1 stlport_vc7.lib
you just need to include the stlport_vc7.lib instead of stlport_vc71.lib

* second problem after successfuly compiling the DocumentLoader in Visual Studio I was getting the following error
Error:
<pre>
Window title: Microsoft Visual C++ Debug Libary
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

After going on debug in the visual studio I found the following line was responsible

<pre>
xSimpleRegistry->open( OUString( RTL_CONSTASCII_USTRINGPARAM("DocumentLoader.rdb") ), sal_True, sal_False );
</pre>

The DocumentLoader.rdb was missing ... I noticed that if I compiled the DocumentLoader exemples from command line with the makefile provided with the exemple a DocumentLoader.rdb was generated. I had a look at the Makefile I isolated the lines which seemed to generate the DocumentLoader.rdb into my Debug folder (or wherever your set your DocumentLoader.exe to be put by Visual Studio) in my Visual Studio project...

<pre>
regmerge c:\travail\DocumentLoader\debug\DocumentLoader.rdb / "C:\ooo\office\program\types.rdb"

regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c connector.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c remotebridge.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c bridgefac.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c uuresolver.uno.dll
</pre>

I launched all the above lines in the prompt shell and it worked I had my DocumentLoader.rdb in my Debug folder

I launched my exe file and it worked, great...

Now I guess I still need to figure out which *.uno.dll needs to be included for which functions used in the programm, but still it's a good start.
If anyone has any information about that (It may actualy be documented somewhere) don't hesitate)

== The Development Tools of the SDK ==

There are several development tools provided with the SDK : idlc, cppumaker, javamaker, rdbmaker, pkgchk, regcomp, regmerge, regview, xml2cmp, uno, and autodoc. You can find a short documentation on these tools at <OOo_SDK>/docs/tools.html and also in [[Documentation/DevGuide/WritingUNO/Required_Files|Developer's Guide]].

See also [[Compiler_versions_used_by_port_maintainers_and_release_engineers|Compiler versions used by port maintainers and release engineers]]

== One Cpp Example ==
If you want to check the Cpp examples, you have to launch first (as mentioned before)
{{Documentation/Linux|
<pre>
./setsdkenv_unix
</pre>
}}
in your shell and then
{{Documentation/Linux|
<pre>
<Ooo>/program/soffice "-accept=socket,host=localhost,port=8100;urp;StarOffice.ServiceManager"
</pre>
}}
For Openoffice.org 2.x, run instead:
{{Documentation/Linux|
<pre>
<Ooo>/program/soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager"
</pre>
}}
Now Openoffice.org is listening on UNO connections through the network (here from localhost only).
We are ready to compile our first example and to check if it works correctly. For that we go in
<OpenOffice.org1.1_SDK>/examples/cpp/DocumentLoader directory.
<pre>
make
</pre>
will compile the example, and
<pre>
make DocumentLoader.run
</pre>
will launch the example. This example only load a Ooowriter's file (test.sxw) provided with the SDK.

Bear in mind the easier way to construct the examples of the SDK is to use the makefiles provided. When you are a beginner with the SDK you always underestimate important steps : for example the registry step discussed later. I estimate to have understand something when I am able to construct it starting with nothing (but skills). In the case of SDK this will take me a long time (and probably will not be finished). Then I can give you an advice : if you want to start a project, begin with modifying an example of the SDK.

Other SDK's examples are discussed later, but you can have a look to :

*[[Counter_Example|Counter example]]

{{Template:Home_Page}}

= See also =
* [[FR/Documentation/Installation_du_SDK|French version of this chapter]].
* [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno|C++ and UNO tutorial]]
* [http://www.codeproject.com/KB/wtl/Wtl_OOo.aspx Prepare the OOo SDK]
* [http://www.oooforum.org/forum/viewtopic.phtml?t=79911&highlight= missing files in sdk]
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal

[[Category:Tutorial]]
[[Category:Cpp]]
[[Category:Uno]]

SDKInstallation

2014-07-07T22:12:06Z

Global667: Add Mac support

{{Documentation/Banner}}
{{Documentation/NeedsRework}}
= How to install the SDK and compile the C++ examples =

For both Linux and Windows the following points are very important if you want to succeed in building C++ components and snippets:
* you need to have OpenOffice.org 1.1.0 or higher installed (SDK won't run without it)
* you need to install the SDK into a directory other than the one of the OOo application

== Installation under Mac OS X (Intel processors) ==

{{Documentation/OSX|
the text below describes the installation of the SDK 4.1 on Mac OS X 10.9.4 with Xcode 4.1.1. It would works for other configurations too.
* Install Xcode. You can get it from the Apple App Store. Perhaps you must be registered as Mac developer under http://www.developer.apple.com
* Install OpenOffice 4.1
* Install MacPorts from http://www.macports.org. Perhaps you need to customize the path. You need MacPorts to install Unix-like software needed by the SDK.
* Install the SDK from http://openoffice.apache.org/downloads.html (You need 4.1.0 for MacOS_x86-64)
* Test the SDK. Open a terminal and look for the SDK folder. Now type and run:
<pre>
cd <SDK_Folder>
./setsdkenv_unix
cd examples/cpp/DocumentLoader
make
soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager" & make DocumentLoder.run
</pre>
}}

== Installation under LINUX ==
{{Documentation/Linux|
The text below describe the installation of the SDK 1.1.0 for OpenOffice.org1.1.0

The Software Development Kit (SDK) works on the top of an existing Openoffice.org installation because of using the same libraries. The SDK requires an Openoffice.org installation.
Even if you don't plan to use Java it is strongly recommended to install the JDK (1.4.1_01 or higher for OOo 1.1 SDK)
Of course a C++ compiler is needed (3.0.1 or higher). GNU make (3.79.1 or higher) is also essential.
When ready, launch :
<pre>
tar xzvf Ooo_1.1.0_LinuxIntel_sdk.tar.gz
</pre>

and go to the new created directory (in this example OpenOffice.org1.1_SDK) and launch the configure script which asks you relevant directories. We give here among others :
* where is your OpenOffice.org installed ? (for me /usr/lib/openoffice : noted <Ooo> later)
* Where is your Java SDK installed ? (for me /usr/java/j2sdk1.4.2_04)

Now you are ready to use the SDK. Every time you want to use it you have to launch the setsdkenv_unix script for environment variables. Automating this is not a problem under UNIX.

From now on, we will always note the SDK directory installation as : <OpenOffice.org1.1_SDK>. Please don't confuse with <Ooo> which is the openoffice.org /program/ directory.

You can find a little complement of this chapter in <OpenOffice.org1.1_SDK>/docs/install.html

The OOo2.0SDK installation is done also by launching the setsdkenv_unix script but asking more information :
<pre>
************************************************************************
*
* SDK environment is prepared for Linux
*
* SDK = /home/smoutou/openoffice.org2.0_sdk
* Office = /opt/openoffice.org2.0
* URE =
* Make = /usr/bin
* Zip = /usr/bin
* C++ Compiler = /usr/bin
* Java = /usr/java/j2sdk1.4.2_04
* Special Output directory = /home/smoutou
* Auto deployment = YES
*
************************************************************************

</pre>
}}

== Installation under Solaris ==
{{Documentation/Linux|
The text below describe the installation of the OpenOffic.org SDK 3.1 for OpenOffice.org3.1

The Software Development Kit (SDK) works on the top of an existing Openoffice.org installation because of using the same libraries. The SDK requires an Openoffice.org installation (default installation directory for Solaris is /opt/openoffice.org/ and /opt/openoffice.org3/)

Depending on which language you wish to use, you will need either:
The Java SDK which can be obtained [http://java.sun.com/javase/downloads/index.jsp here].
Or a C++ complier (g++ 3.0.1 or higher is recommended). As well as GNU make (3.79.1 or higher) is also essential.

First download the Solaris SDK from [http://download.openoffice.org/sdk/index.html here].

Now run the install script by typing the following command. This script will prompt you for a temporary directory where it will extract the installation package. Just press enter and the package will be extracted into the directory shown in brackets (in this case /var/tmp/unpack_openofficeorg). If you wish to extract the package into a separate directory, type in the full directory path at the prompt.

<pre>
# sh OOo-SDK_3.1.1_SolarisSparc_install_en-US.sh
Select the directory in which to save the unpacked files. [/var/tmp/unpack_openofficeorg]

File is being checked for errors ...
Unpacking ...
All files have been successfully unpacked.
</pre>

Now navigate into the packages directory under the unpacked installation directory that was just created.

<pre>
# cd /var/tmp/unpack_openofficeorg/packages
</pre>

Go ahead an install the SDK package using pfexec.

<pre>
# pfexec pkgadd -d .
</pre>

To check if the installation succeeded, attempt to navigate into the sdk directory under the OpenOffic.org basis directory.
<pre>
# cd /opt/openoffice.org/basis3.1/sdk
# ls
bin/ examples/ setsdkenv_unix.csh.in
classes/ idl/ setsdkenv_unix.sh.in
config.guess include/ settings/
config.sub index.html share/
configure.pl lib/
docs/ setsdkenv_unix
</pre>

Now you are ready to use the SDK. Every time you want to use it you have to launch the setsdkenv_unix script for environment variables. Automating this is not a problem under UNIX. You can find a little complement of this chapter in <OpenOffice.org1.1_SDK>/docs/install.html

In order to use the SDK you need to first execute the setsdkevn_unx script in the <OpenOffice.org>/basis3.1/sdk directory (/opt/openoffice.org/basis3.1/sdk for me). Before you execute this script, you need to locate all of the development tools for the language you will be using. Below is a list of the tools that the script prompts for and the locations of the tools on my machine.

<pre>
OpenOffice.org3 installation = /opt/openoffice.org3
GNU make 3.79.1 or higher = /usr/bin
C++ compiler (g++ 3.0.1 or higher) = /usr/bin
Zip = /usr/bin
Java = /usr/jdk/latest/
</pre>

Input the paths to your development tools when prompted.

You are now ready to use the OpenOffice SDK
}}

== Installation under Windows ==
{{Documentation/Windows|

You need a compiler out of the Microsoft Visual Studio family (other compilers like MinGW have turned out to be hard to configure for OOo on Windows).
The first thing after having installed the SDK is to launch the configureWindowsNT.bat and set all the necessary directories for proper use of the SDK.
If that has been done you have already installed everything, but *wait* one very important thing you should still know of:
Every time you want to run your own code or one of the SDK examples you need to launch the setsdkenv_Windows batch file from your command shell. The title of it should now be "Shell prepared for SDK". Happy coding, compiling and building now (I tell you it's easy from now on!).
GanescuCarmen describes some problems he encounter when trying SDK examples under Windows :
“I also use the 1.1 OO version.

I had a lots of problems.
Finally I succeeded to obtain the the header files, and in VC I needed some library to be included into project and some files(uno.idl) to be added to rdb files.
It was very hard to understand what it means registry(the rdb file not the Registry itself).

I was expecting to register something in Registry but it wasn't like this.
And with the service manager I had some problems, with the port, because the connection with 8100 port was not done.
I had to modify a file and to add some code for 8100 port.

But I did it and it works now.”
}}

== Installing with the free MS Visual C++ Toolkit 2003 ==
{{Documentation/HelpNeeded|This section needs help for update because '''MS Visual C++ Toolkit 2003''' seems no more available. Please have a look at Microsoft for the free Visual C++ tools at the moment.}}
I have installed DevCpp to have a make executable file.
I have downloaded the free Visual C++ Toolkit 2003 here :
http://www.microsoft.com/downloads/details.aspx?FamilyID=272be09d-40bb-49fd-9cb0-4bfa122fa91b&displaylang=en

and then I have installed it. '''(This link is broken.)'''

I launch first C:\openoffice\OpenOffice.org2.0_SDK\configureWindowsNT.bat
which asks any questions :
<pre>
set OO_SDK_HOME=C:\openoffice\OpenOffice.org2.0_SDK
set OFFICE_HOME=C:\Program Files\OpenOffice.org 2.0
set OO_SDK_MAKE_HOME=C:\Dev-C++\Bin
set OO_SDK_CPP_HOME=C:\Program Files\Microsoft Visual C++ Toolkit 2003\Bin
set OO_SDK_JAVA_HOME=C:\Program Files\Java\jdk1.5.0_03
</pre>

and I am ready to launch setsdkenv_windows.bat

I have modified the following file :
C:\openoffice\OpenOffice.org2.0_SDK\examples\DevelopersGuide\ProfUNO\CppBinding\office_connect.cxx
to change the port accordingly to what OOo is listening.

I have modified the makefile :
added :
<pre>
CC_INCLUDES = -I"C:\Program Files\Microsoft Visual C++ Toolkit 2003\include" \
-I"C:\openoffice\OpenOffice.org2.0_SDK\include"
</pre>

and added libraries too :

<pre>
$(OUT_BIN)/%$(EXE_EXT) : $(SAMPLE_OBJ_OUT)/%.$(OBJ_EXT)
-$(MKDIR) $(subst /,$(PS),$(@D))
-$(MKDIR) $(subst /,$(PS),$(SAMPLE_GEN_OUT))
ifeq "$(OS)" "WIN"
$(LINK) $(EXE_LINK_FLAGS) /OUT:$@ /MAP:$(SAMPLE_GEN_OUT)/$(subst $(EXE_EXT),.map,$(@F)) \
$< $(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB)\
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libcp.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libc.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\oldnames.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\kernel32.lib"
else
$(LINK) $(EXE_LINK_FLAGS) $(LINK_LIBS) -o $@ $< \
$(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB) $(STDC++LIB)
endif
</pre>
I suppose there is a more straightforward way to add these libraries with adding the corresponding include path but I am unable to do that with VC++.

I find a solution of the previous problem three weeks later. My problem comes in fact from a bug in setsdkenv_windows.bat. A little correction in the file setsdkenv_windows.bat makes it possible to avoid the makefile modifications :
Put :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "C:\Program Files\Microsoft Visual C++ Toolkit 2003\VCVARS32.bat"
</pre>

instead of :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "%OO_SDK_CPP_HOME%\VCVARS32.bat"
</pre>
I think
<pre>
%OO_SDK_CPP_HOME%\..\VCVARS32.bat
</pre>
could work too (but not checked). You can also move vcvars32.bat in %OO_SDK_CPP_HOME%
("C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin" for me).

== Other Windows Installations descriptions ==

You can find in [http://www.oooforum.org/forum/viewtopic.phtml?t=23772 OOoForum] a post entitled Guide for develop OpenOffice apps with VC++ .net (by [[CppSDKAuthors|LarsB]])

1.Download and install OpenOffice.

2.Download and install OpenOffice SDK

3.Create a new folder inludecpp in <oo_sdk_path>

4.Open Dos console change directory to <oo_sdk_path>\windows\bin

4.1 run cppumaker with followig paramerers
<pre>
cppumaker -BUCR -O <oo_sdk_path>\includecpp <office_programm_dir>\types.rdb
</pre>
or better with
<pre>
cppumaker -Gc -BUCR -O<includes_path> <ooffice_path>\URE\misc\types.rdb <ooffice_path>\Basis\program\offapi.rdb
</pre>
in recent versions.

(Attention: If you recieve a init error, copy types.rdb into the <oo_sdk_path>\windows\bin folder!)
After that all hpp and hdl files should be created in <oo_sdk_path>\includecpp

5.Open Visual Studio and create a new Win32 Console Application.
Applay the following changes to your project.

5.1. Tools ->Options->Projects->VC++ Directories -> Include Files
Add \include directory and <oo_sdk_path>\includecpp

5.2. Tools ->Options->Projects->VC++ Directories -> Library files
Add <oo_sdk_path>\windows\lib directory

5.3. Tools ->Options->Projects->VC++ Directories -> Executable files
Add <office_programm_dir>\program directory (location where you installed the version of the OpenOffice)

5.4 Open the Project Settings

5.4.1 Change Configuration to all All Configurations (the combobox in the left corner of the window)

5.4.2 Add the additional libraries

Properties->Linker->ComandLine in the Additional Options tab the library files
isal.lib icppu.lib icppuhelper.lib isal.lib isalhelper.lib ireg.lib irmcxt.lib stlport_vc71.lib

6.(example) Add the DocumentLoader.cxx from the cpp examples of the sdk
and compile. The source should compile without errors.

INFO : If you got the following error have a look at the solution 2 postings above!
Up to now, with the steps above i got the following error, when i run the DocumentLoader example.
The error is thrown, when the prog execution reach the following line:

<pre>

Reference< XSimpleRegistry > xSimpleRegistry( ::cppu::createSimpleRegistry() );
</pre>

with error shown below :

<pre>
Error:
Window title: Microsoft Visual C++ Debug Library
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

If somebody has experience with this kind of error it will be nice if he could
post a solution. So that here is a complete little guide for OpenOffice with VC++ .NET

Regards
[[CppSDKAuthors|Lars]]

[[CppSDKAuthors|François]] has improved the complete procedure with remarks :
Following all the steps I (_francois_) encountered two problems

* first in point 4.4.2

But there I guess it's because the procedure was meant for SDK 2 and I'm using SDK 1.1
The stlport_vc71.lib which you must include is distributed with the SDK 2 in the SDK 1.1 stlport_vc7.lib
you just need to include the stlport_vc7.lib instead of stlport_vc71.lib

* second problem after successfuly compiling the DocumentLoader in Visual Studio I was getting the following error
Error:
<pre>
Window title: Microsoft Visual C++ Debug Libary
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

After going on debug in the visual studio I found the following line was responsible

<pre>
xSimpleRegistry->open( OUString( RTL_CONSTASCII_USTRINGPARAM("DocumentLoader.rdb") ), sal_True, sal_False );
</pre>

The DocumentLoader.rdb was missing ... I noticed that if I compiled the DocumentLoader exemples from command line with the makefile provided with the exemple a DocumentLoader.rdb was generated. I had a look at the Makefile I isolated the lines which seemed to generate the DocumentLoader.rdb into my Debug folder (or wherever your set your DocumentLoader.exe to be put by Visual Studio) in my Visual Studio project...

<pre>
regmerge c:\travail\DocumentLoader\debug\DocumentLoader.rdb / "C:\ooo\office\program\types.rdb"

regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c connector.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c remotebridge.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c bridgefac.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c uuresolver.uno.dll
</pre>

I launched all the above lines in the prompt shell and it worked I had my DocumentLoader.rdb in my Debug folder

I launched my exe file and it worked, great...

Now I guess I still need to figure out which *.uno.dll needs to be included for which functions used in the programm, but still it's a good start.
If anyone has any information about that (It may actualy be documented somewhere) don't hesitate)

== The Development Tools of the SDK ==

There are several development tools provided with the SDK : idlc, cppumaker, javamaker, rdbmaker, pkgchk, regcomp, regmerge, regview, xml2cmp, uno, and autodoc. You can find a short documentation on these tools at <OOo_SDK>/docs/tools.html and also in [[Documentation/DevGuide/WritingUNO/Required_Files|Developer's Guide]].

See also [[Compiler_versions_used_by_port_maintainers_and_release_engineers|Compiler versions used by port maintainers and release engineers]]

== One Cpp Example ==
If you want to check the Cpp examples, you have to launch first (as mentioned before)
{{Documentation/Linux|
<pre>
./setsdkenv_unix
</pre>
}}
in your shell and then
{{Documentation/Linux|
<pre>
<Ooo>/program/soffice "-accept=socket,host=localhost,port=8100;urp;StarOffice.ServiceManager"
</pre>
}}
For Openoffice.org 2.x, run instead:
{{Documentation/Linux|
<pre>
<Ooo>/program/soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager"
</pre>
}}
Now Openoffice.org is listening on UNO connections through the network (here from localhost only).
We are ready to compile our first example and to check if it works correctly. For that we go in
<OpenOffice.org1.1_SDK>/examples/cpp/DocumentLoader directory.
<pre>
make
</pre>
will compile the example, and
<pre>
make DocumentLoader.run
</pre>
will launch the example. This example only load a Ooowriter's file (test.sxw) provided with the SDK.

Bear in mind the easier way to construct the examples of the SDK is to use the makefiles provided. When you are a beginner with the SDK you always underestimate important steps : for example the registry step discussed later. I estimate to have understand something when I am able to construct it starting with nothing (but skills). In the case of SDK this will take me a long time (and probably will not be finished). Then I can give you an advice : if you want to start a project, begin with modifying an example of the SDK.

Other SDK's examples are discussed later, but you can have a look to :

*[[Counter_Example|Counter example]]

{{Template:Home_Page}}

= See also =
* [[FR/Documentation/Installation_du_SDK|French version of this chapter]].
* [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno|C++ and UNO tutorial]]
* [http://www.codeproject.com/KB/wtl/Wtl_OOo.aspx Prepare the OOo SDK]
* [http://www.oooforum.org/forum/viewtopic.phtml?t=79911&highlight= missing files in sdk]
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal

[[Category:Tutorial]]
[[Category:Cpp]]
[[Category:Uno]]

SDKInstallation

2014-07-07T22:09:44Z

Global667: Add Mac support (checkpoint save)

{{Documentation/Banner}}
{{Documentation/NeedsRework}}
= How to install the SDK and compile the C++ examples =

For both Linux and Windows the following points are very important if you want to succeed in building C++ components and snippets:
* you need to have OpenOffice.org 1.1.0 or higher installed (SDK won't run without it)
* you need to install the SDK into a directory other than the one of the OOo application

== Installation under Mac OS X (Intel processors) ==

{{Documentation/OSX|

the text below describes the installation of the SDK 4.1 on Mac OS X 10.9.4 with Xcode 4.1.1. It would works for other configurations too.

* Install Xcode. You can get it from the Apple App Store. Perhaps you must be registered as Mac developer under http://www.developer.apple.com

* Install OpenOffice 4.1

* Install MacPorts from http://www.macports.org. Perhaps you need to customize the path. You need MacPorts to install Unix-like software needed by the SDK.

* Install the SDK from http://openoffice.apache.org/downloads.html (You need 4.1.0 for MacOS_x86-64)

* Test the SDK. Open a terminal and look for the SDK folder. Now type and run:

<pre>
cd <SDK_Folder>
./setsdkenv_unix
cd examples/cpp/DocumentLoader
make
soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager" & make DocumentLoder.run
</pre>

}}

== Installation under LINUX ==
{{Documentation/Linux|
The text below describe the installation of the SDK 1.1.0 for OpenOffice.org1.1.0

The Software Development Kit (SDK) works on the top of an existing Openoffice.org installation because of using the same libraries. The SDK requires an Openoffice.org installation.
Even if you don't plan to use Java it is strongly recommended to install the JDK (1.4.1_01 or higher for OOo 1.1 SDK)
Of course a C++ compiler is needed (3.0.1 or higher). GNU make (3.79.1 or higher) is also essential.
When ready, launch :
<pre>
tar xzvf Ooo_1.1.0_LinuxIntel_sdk.tar.gz
</pre>

and go to the new created directory (in this example OpenOffice.org1.1_SDK) and launch the configure script which asks you relevant directories. We give here among others :
* where is your OpenOffice.org installed ? (for me /usr/lib/openoffice : noted <Ooo> later)
* Where is your Java SDK installed ? (for me /usr/java/j2sdk1.4.2_04)

Now you are ready to use the SDK. Every time you want to use it you have to launch the setsdkenv_unix script for environment variables. Automating this is not a problem under UNIX.

From now on, we will always note the SDK directory installation as : <OpenOffice.org1.1_SDK>. Please don't confuse with <Ooo> which is the openoffice.org /program/ directory.

You can find a little complement of this chapter in <OpenOffice.org1.1_SDK>/docs/install.html

The OOo2.0SDK installation is done also by launching the setsdkenv_unix script but asking more information :
<pre>
************************************************************************
*
* SDK environment is prepared for Linux
*
* SDK = /home/smoutou/openoffice.org2.0_sdk
* Office = /opt/openoffice.org2.0
* URE =
* Make = /usr/bin
* Zip = /usr/bin
* C++ Compiler = /usr/bin
* Java = /usr/java/j2sdk1.4.2_04
* Special Output directory = /home/smoutou
* Auto deployment = YES
*
************************************************************************

</pre>
}}

== Installation under Solaris ==
{{Documentation/Linux|
The text below describe the installation of the OpenOffic.org SDK 3.1 for OpenOffice.org3.1

The Software Development Kit (SDK) works on the top of an existing Openoffice.org installation because of using the same libraries. The SDK requires an Openoffice.org installation (default installation directory for Solaris is /opt/openoffice.org/ and /opt/openoffice.org3/)

Depending on which language you wish to use, you will need either:
The Java SDK which can be obtained [http://java.sun.com/javase/downloads/index.jsp here].
Or a C++ complier (g++ 3.0.1 or higher is recommended). As well as GNU make (3.79.1 or higher) is also essential.

First download the Solaris SDK from [http://download.openoffice.org/sdk/index.html here].

Now run the install script by typing the following command. This script will prompt you for a temporary directory where it will extract the installation package. Just press enter and the package will be extracted into the directory shown in brackets (in this case /var/tmp/unpack_openofficeorg). If you wish to extract the package into a separate directory, type in the full directory path at the prompt.

<pre>
# sh OOo-SDK_3.1.1_SolarisSparc_install_en-US.sh
Select the directory in which to save the unpacked files. [/var/tmp/unpack_openofficeorg]

File is being checked for errors ...
Unpacking ...
All files have been successfully unpacked.
</pre>

Now navigate into the packages directory under the unpacked installation directory that was just created.

<pre>
# cd /var/tmp/unpack_openofficeorg/packages
</pre>

Go ahead an install the SDK package using pfexec.

<pre>
# pfexec pkgadd -d .
</pre>

To check if the installation succeeded, attempt to navigate into the sdk directory under the OpenOffic.org basis directory.
<pre>
# cd /opt/openoffice.org/basis3.1/sdk
# ls
bin/ examples/ setsdkenv_unix.csh.in
classes/ idl/ setsdkenv_unix.sh.in
config.guess include/ settings/
config.sub index.html share/
configure.pl lib/
docs/ setsdkenv_unix
</pre>

Now you are ready to use the SDK. Every time you want to use it you have to launch the setsdkenv_unix script for environment variables. Automating this is not a problem under UNIX. You can find a little complement of this chapter in <OpenOffice.org1.1_SDK>/docs/install.html

In order to use the SDK you need to first execute the setsdkevn_unx script in the <OpenOffice.org>/basis3.1/sdk directory (/opt/openoffice.org/basis3.1/sdk for me). Before you execute this script, you need to locate all of the development tools for the language you will be using. Below is a list of the tools that the script prompts for and the locations of the tools on my machine.

<pre>
OpenOffice.org3 installation = /opt/openoffice.org3
GNU make 3.79.1 or higher = /usr/bin
C++ compiler (g++ 3.0.1 or higher) = /usr/bin
Zip = /usr/bin
Java = /usr/jdk/latest/
</pre>

Input the paths to your development tools when prompted.

You are now ready to use the OpenOffice SDK
}}

== Installation under Windows ==
{{Documentation/Windows|

You need a compiler out of the Microsoft Visual Studio family (other compilers like MinGW have turned out to be hard to configure for OOo on Windows).
The first thing after having installed the SDK is to launch the configureWindowsNT.bat and set all the necessary directories for proper use of the SDK.
If that has been done you have already installed everything, but *wait* one very important thing you should still know of:
Every time you want to run your own code or one of the SDK examples you need to launch the setsdkenv_Windows batch file from your command shell. The title of it should now be "Shell prepared for SDK". Happy coding, compiling and building now (I tell you it's easy from now on!).
GanescuCarmen describes some problems he encounter when trying SDK examples under Windows :
“I also use the 1.1 OO version.

I had a lots of problems.
Finally I succeeded to obtain the the header files, and in VC I needed some library to be included into project and some files(uno.idl) to be added to rdb files.
It was very hard to understand what it means registry(the rdb file not the Registry itself).

I was expecting to register something in Registry but it wasn't like this.
And with the service manager I had some problems, with the port, because the connection with 8100 port was not done.
I had to modify a file and to add some code for 8100 port.

But I did it and it works now.”
}}

== Installing with the free MS Visual C++ Toolkit 2003 ==
{{Documentation/HelpNeeded|This section needs help for update because '''MS Visual C++ Toolkit 2003''' seems no more available. Please have a look at Microsoft for the free Visual C++ tools at the moment.}}
I have installed DevCpp to have a make executable file.
I have downloaded the free Visual C++ Toolkit 2003 here :
http://www.microsoft.com/downloads/details.aspx?FamilyID=272be09d-40bb-49fd-9cb0-4bfa122fa91b&displaylang=en

and then I have installed it. '''(This link is broken.)'''

I launch first C:\openoffice\OpenOffice.org2.0_SDK\configureWindowsNT.bat
which asks any questions :
<pre>
set OO_SDK_HOME=C:\openoffice\OpenOffice.org2.0_SDK
set OFFICE_HOME=C:\Program Files\OpenOffice.org 2.0
set OO_SDK_MAKE_HOME=C:\Dev-C++\Bin
set OO_SDK_CPP_HOME=C:\Program Files\Microsoft Visual C++ Toolkit 2003\Bin
set OO_SDK_JAVA_HOME=C:\Program Files\Java\jdk1.5.0_03
</pre>

and I am ready to launch setsdkenv_windows.bat

I have modified the following file :
C:\openoffice\OpenOffice.org2.0_SDK\examples\DevelopersGuide\ProfUNO\CppBinding\office_connect.cxx
to change the port accordingly to what OOo is listening.

I have modified the makefile :
added :
<pre>
CC_INCLUDES = -I"C:\Program Files\Microsoft Visual C++ Toolkit 2003\include" \
-I"C:\openoffice\OpenOffice.org2.0_SDK\include"
</pre>

and added libraries too :

<pre>
$(OUT_BIN)/%$(EXE_EXT) : $(SAMPLE_OBJ_OUT)/%.$(OBJ_EXT)
-$(MKDIR) $(subst /,$(PS),$(@D))
-$(MKDIR) $(subst /,$(PS),$(SAMPLE_GEN_OUT))
ifeq "$(OS)" "WIN"
$(LINK) $(EXE_LINK_FLAGS) /OUT:$@ /MAP:$(SAMPLE_GEN_OUT)/$(subst $(EXE_EXT),.map,$(@F)) \
$< $(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB)\
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libcp.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\libc.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\oldnames.lib" \
"C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib\kernel32.lib"
else
$(LINK) $(EXE_LINK_FLAGS) $(LINK_LIBS) -o $@ $< \
$(CPPUHELPERLIB) $(CPPULIB) $(SALHELPERLIB) $(SALLIB) $(STLPORTLIB) $(STDC++LIB)
endif
</pre>
I suppose there is a more straightforward way to add these libraries with adding the corresponding include path but I am unable to do that with VC++.

I find a solution of the previous problem three weeks later. My problem comes in fact from a bug in setsdkenv_windows.bat. A little correction in the file setsdkenv_windows.bat makes it possible to avoid the makefile modifications :
Put :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "C:\Program Files\Microsoft Visual C++ Toolkit 2003\VCVARS32.bat"
</pre>

instead of :
<pre>
REM Set environment for C++ compiler tools, if necessary.
if defined OO_SDK_CPP_HOME call "%OO_SDK_CPP_HOME%\VCVARS32.bat"
</pre>
I think
<pre>
%OO_SDK_CPP_HOME%\..\VCVARS32.bat
</pre>
could work too (but not checked). You can also move vcvars32.bat in %OO_SDK_CPP_HOME%
("C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin" for me).

== Other Windows Installations descriptions ==

You can find in [http://www.oooforum.org/forum/viewtopic.phtml?t=23772 OOoForum] a post entitled Guide for develop OpenOffice apps with VC++ .net (by [[CppSDKAuthors|LarsB]])

1.Download and install OpenOffice.

2.Download and install OpenOffice SDK

3.Create a new folder inludecpp in <oo_sdk_path>

4.Open Dos console change directory to <oo_sdk_path>\windows\bin

4.1 run cppumaker with followig paramerers
<pre>
cppumaker -BUCR -O <oo_sdk_path>\includecpp <office_programm_dir>\types.rdb
</pre>
or better with
<pre>
cppumaker -Gc -BUCR -O<includes_path> <ooffice_path>\URE\misc\types.rdb <ooffice_path>\Basis\program\offapi.rdb
</pre>
in recent versions.

(Attention: If you recieve a init error, copy types.rdb into the <oo_sdk_path>\windows\bin folder!)
After that all hpp and hdl files should be created in <oo_sdk_path>\includecpp

5.Open Visual Studio and create a new Win32 Console Application.
Applay the following changes to your project.

5.1. Tools ->Options->Projects->VC++ Directories -> Include Files
Add \include directory and <oo_sdk_path>\includecpp

5.2. Tools ->Options->Projects->VC++ Directories -> Library files
Add <oo_sdk_path>\windows\lib directory

5.3. Tools ->Options->Projects->VC++ Directories -> Executable files
Add <office_programm_dir>\program directory (location where you installed the version of the OpenOffice)

5.4 Open the Project Settings

5.4.1 Change Configuration to all All Configurations (the combobox in the left corner of the window)

5.4.2 Add the additional libraries

Properties->Linker->ComandLine in the Additional Options tab the library files
isal.lib icppu.lib icppuhelper.lib isal.lib isalhelper.lib ireg.lib irmcxt.lib stlport_vc71.lib

6.(example) Add the DocumentLoader.cxx from the cpp examples of the sdk
and compile. The source should compile without errors.

INFO : If you got the following error have a look at the solution 2 postings above!
Up to now, with the steps above i got the following error, when i run the DocumentLoader example.
The error is thrown, when the prog execution reach the following line:

<pre>

Reference< XSimpleRegistry > xSimpleRegistry( ::cppu::createSimpleRegistry() );
</pre>

with error shown below :

<pre>
Error:
Window title: Microsoft Visual C++ Debug Library
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

If somebody has experience with this kind of error it will be nice if he could
post a solution. So that here is a complete little guide for OpenOffice with VC++ .NET

Regards
[[CppSDKAuthors|Lars]]

[[CppSDKAuthors|François]] has improved the complete procedure with remarks :
Following all the steps I (_francois_) encountered two problems

* first in point 4.4.2

But there I guess it's because the procedure was meant for SDK 2 and I'm using SDK 1.1
The stlport_vc71.lib which you must include is distributed with the SDK 2 in the SDK 1.1 stlport_vc7.lib
you just need to include the stlport_vc7.lib instead of stlport_vc71.lib

* second problem after successfuly compiling the DocumentLoader in Visual Studio I was getting the following error
Error:
<pre>
Window title: Microsoft Visual C++ Debug Libary
Headline: Debug Error
Msg: This application has requested the Runtime to terminate it in an usual way.
Please contact the support team for more information.
</pre>

After going on debug in the visual studio I found the following line was responsible

<pre>
xSimpleRegistry->open( OUString( RTL_CONSTASCII_USTRINGPARAM("DocumentLoader.rdb") ), sal_True, sal_False );
</pre>

The DocumentLoader.rdb was missing ... I noticed that if I compiled the DocumentLoader exemples from command line with the makefile provided with the exemple a DocumentLoader.rdb was generated. I had a look at the Makefile I isolated the lines which seemed to generate the DocumentLoader.rdb into my Debug folder (or wherever your set your DocumentLoader.exe to be put by Visual Studio) in my Visual Studio project...

<pre>
regmerge c:\travail\DocumentLoader\debug\DocumentLoader.rdb / "C:\ooo\office\program\types.rdb"

regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c connector.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c remotebridge.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c bridgefac.uno.dll
regcomp -register -r c:\travail\DocumentLoader\debug\DocumentLoader.rdb -c uuresolver.uno.dll
</pre>

I launched all the above lines in the prompt shell and it worked I had my DocumentLoader.rdb in my Debug folder

I launched my exe file and it worked, great...

Now I guess I still need to figure out which *.uno.dll needs to be included for which functions used in the programm, but still it's a good start.
If anyone has any information about that (It may actualy be documented somewhere) don't hesitate)

== The Development Tools of the SDK ==

There are several development tools provided with the SDK : idlc, cppumaker, javamaker, rdbmaker, pkgchk, regcomp, regmerge, regview, xml2cmp, uno, and autodoc. You can find a short documentation on these tools at <OOo_SDK>/docs/tools.html and also in [[Documentation/DevGuide/WritingUNO/Required_Files|Developer's Guide]].

See also [[Compiler_versions_used_by_port_maintainers_and_release_engineers|Compiler versions used by port maintainers and release engineers]]

== One Cpp Example ==
If you want to check the Cpp examples, you have to launch first (as mentioned before)
{{Documentation/Linux|
<pre>
./setsdkenv_unix
</pre>
}}
in your shell and then
{{Documentation/Linux|
<pre>
<Ooo>/program/soffice "-accept=socket,host=localhost,port=8100;urp;StarOffice.ServiceManager"
</pre>
}}
For Openoffice.org 2.x, run instead:
{{Documentation/Linux|
<pre>
<Ooo>/program/soffice "-accept=socket,host=localhost,port=2083;urp;StarOffice.ServiceManager"
</pre>
}}
Now Openoffice.org is listening on UNO connections through the network (here from localhost only).
We are ready to compile our first example and to check if it works correctly. For that we go in
<OpenOffice.org1.1_SDK>/examples/cpp/DocumentLoader directory.
<pre>
make
</pre>
will compile the example, and
<pre>
make DocumentLoader.run
</pre>
will launch the example. This example only load a Ooowriter's file (test.sxw) provided with the SDK.

Bear in mind the easier way to construct the examples of the SDK is to use the makefiles provided. When you are a beginner with the SDK you always underestimate important steps : for example the registry step discussed later. I estimate to have understand something when I am able to construct it starting with nothing (but skills). In the case of SDK this will take me a long time (and probably will not be finished). Then I can give you an advice : if you want to start a project, begin with modifying an example of the SDK.

Other SDK's examples are discussed later, but you can have a look to :

*[[Counter_Example|Counter example]]

{{Template:Home_Page}}

= See also =
* [[FR/Documentation/Installation_du_SDK|French version of this chapter]].
* [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno|C++ and UNO tutorial]]
* [http://www.codeproject.com/KB/wtl/Wtl_OOo.aspx Prepare the OOo SDK]
* [http://www.oooforum.org/forum/viewtopic.phtml?t=79911&highlight= missing files in sdk]
* Writing a Program to Control OpenOffice.org, by Franco Pingiori — [http://www.linuxjournal.com/article/8550 Part 1] and [http://www.linuxjournal.com/article/8608 Part 2], Linux Journal

[[Category:Tutorial]]
[[Category:Cpp]]
[[Category:Uno]]

DE/Makro Basic Tutorial

2006-09-06T01:33:07Z

Global667: /* Properties */

[[Category:de.openoffice.org|Makro Basic Tutorial]]

{| cellspacing=0 cellpadding=5 style="border: 1px solid black;"
| bgcolor=orange colspan=2 |'''Achtung, work in progress'''
Dieses Dokument wird gerade übersetzt, wer mag, darf auch gerne helfen.
|-
|'''Arbeitstitel:''' || "Einführung: Basic für OOo-Erweiterungen"
|-
|'''Originaldokument:''' || [[Extensions_development_basic]] 
|-
|'''Ursprünglicher Autor:''' || Ian Laurenson
|-
| offene Fragen: || sind mit ??? gekennzeichnet
|}

Diese Seite soll Ihnen eine Einführung in das Schreiben von Makros mit OpenOffice.org Basic geben. Grundkenntnisse im Programmieren werden vorausgesetzt. Bitte fühlen Sie sich frei, diese Seite zu editieren, um sie lesbarer zu machen. Ich hoffe, das Sie Ihnen von Nutzen sein wird.

Wenn Sie bereits mit den Grundlagen vertraut sind, können Sie sich auch direkt im KochBuch ([[CookBook]]) Wrapper (Hüllfunktionen ???) und Beispiele anschauen.

= Wohin schreibe ich den Code? =

Der Basic-Code wird bei OpenOffice.org in '''Modulen''' gespeichert, die in '''Bibliotheken''' zusammengefasst sind.

Eine Bibliothek kann
* '''allgemein''', also für die gesamte (Netzwerk-) Installation verfügbar sein ("OOo Makros und Dialoge")
* nur für den aktuellen '''Benutzer''' verfügbar sein ("Meine Makros und Dialoge")
* in einem '''Dokument''' oder in einer Vorlage abgelegt sein, so dass ihr Code nur zur Verfügung steht, wenn das Dokument geöffnet ist.
Bibliotheken, die nicht in einem Dokument abgelegt sind (also allgemein oder für den aktuellen Benutzer verfügbare Bibliotheken) werden im Folgenden als ''OpenOffice.org Bibliotheken'' zusammengefasst.

Der physische Speicherort für diese OpenOffice.org Bibliotheken wird unter '''Extras > Optionen… > OpenOffice.org > Pfade > BASIC''' festgelegt.

{| border="1"
|'''Anmerkung:'''
|Hüten Sie sich, Bibliotheken auf Dateisystem-Ebene zu verschieben oder zu kopieren. Benutzen Sie stattdessen den Dialog "Makros verwalten" oder den Paket-Manager
|}

Module in Bibliotheken können maximal 64kb groß sein. Eine Bibliothek kann bis zu 16 000 Module enthalten. Weitere Infos finden Sie in der Online-Hilfe unter "Module und Bibliotheken" (???).

= Die Entwicklungsumgebung (IDE) =

Öffnen Sie die Entwicklungsumgebung:
* in OOo 1.1.x unter '''Extras > Makros > Makro ...'''
* in OOo 1.9.x und höher unter ''' Extras > Makros > Makros verwalten > OpenOffice.org Basic...'''

Zum Einstieg benutzen wir das "Modul1" aus der Bibliothek "Standard" des aktuellen Benutzers:

Geben Sie einen Namen für das neue Makro ein: "HelloWorld"

Wählen Sie die Option '''Standard''' im Auswahlfeld "Makro aus:"

Klicken Sie auf '''Neu'''

Jetzt sollten Sie etwa folgendes sehen:

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub

Sub HelloWorld

End Sub
</code>

Der Cursor sollte am Anfang der Zeile <tt>Sub HelloWorld</tt> stehen.

{| border="1"
|'''Achtung:'''
|Das geöffnete IDE-Fenster ist sowohl über das Menü im OpenOffice.org-Fenster als auch über die Programmleiste des Betriebssystems erreichbar.
|}

= Eingeben von Programm-Code =

Löschen Sie folgende Zeilen:

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub
</code>

Schreiben Sie unterhalb der Zeile "Sub HelloWorld": <tt>msgbox "Hello World!"</tt>, so dass es in etwa so aussieht:

<code>[oobas]
Sub HelloWorld
msgbox "Hello World!"
End Sub
</code>

{| border="1"
|'''Achtung:'''
|Die IDE beherrscht zwar keine "code completion"(->dt.Auto-Vervollständigung), also die Fähigkeit eines Editors den Text automatisch zu vervollständigen, um den Schreibprozess zu beschleunigen, während der Eingabe, verfügt aber über eine kontext-sensitive Hilfe, wenn Sie während der Eingabe F1 oder "Hilfe" drücken oder der Cursor in einem Befehl steht. Bei OpenOffice.org Basic-Befehlen wird die Groß- und Kleinschreibung nicht unterschieden. So sind die Eingaben msgbox, MSGBOX oder Msgbox äquivalent. Strings (Textvariablen) werden in doppelte Anführrungszeichen eingeschlossen.
|-
|}

= Den Code ausführen =

Hierfür gibt es mehrere Möglichkeiten:

* direkt aus der IDE: das Symbol '''Ausführen''' (das 3. Symbol in der 2. Leiste) ruft das ERSTE Makro des aktuellen Moduls auf.
* aus dem Menü "Extras":
** (Version 1.1.x) '''Extras > Makros > Makro…''';
** (Version 1.9.x und höher) '''Extras > Makro > Makro auführen…'''
* Dem Makro ein Tastaturkürzel zuweisen (todo).
* Dem Makro einen Menüeintrag zuweisen (todo).
* Dem Makro ein Symbolleisten-Symbol zuweisen (todo).
* Ein Kontroll-Element in einem Dokument erstellen (todo).
* Das Makro einem Ereignis zuweisen (todo)

Führen Sie für den Anfang die "HelloWorld"-Subroutine aus, indem Sie auf das '''Ausführen'''-Symbol klicken. Ein kleiner Dialog mit dem Titel "soffice" und dem Text "Hello World" sollte aufpoppen.

= Speichern des Code =

Der Code wird immer automatisch gespeichert, wenn sein Container gespeichert wird. Wenn das Modul also in einer (allgemeinen oder benutzerspezifischen) OpenOffice.org-Bibliothek enthalten ist, wird es beim Schließen der Anwendung OpenOffice.org gespeichert. Entsprechend werden Dokument-interne Bibliotheken biem Speichern des Dokuments mit-gesichert.

Auf der Standard-Symbolleiste der IDE (normalerweise die oberste Symbolleiste) finden Sie ein Symbol "Speichern". Befindet sich der Code in einem Dokument oder einer Vorlage, dann speichert der Klick auf dieses Symbol das gesamte Dokument. Handelt es sich dagegen um eine OpenOffice.org-Bibliothek, wird nur die aktuelle Bibliothek gespeichert.

= Variablen =

Bei Variablen kann durch <tt>Option Explicit</tt> zu Beginn des Moduls die explizite Deklaration erzwungen werden. Zu Sinn und Unsinn des Deklarierens von Variablen lesen Sie [http://www.oooforum.org/forum/viewtopic.phtml?t=5845 diese Diskussion].

In dieser Diskussion vertritt der ursprüngliche Autor dieses Wiki-Beitrags die Position, dass Variablen immer deklariert werden sollten. Mittlerweile hat er seine Meinung geändert. Kurz: es ist eine Frage des persönlichen Geschmacks. Unabhängig davon sollten nach Auffassung des ursprünglichen Autors Variablen nach folgener Konvention benannt werden, die auch bei den Beispielen aus diesem Wiki verwendet wurde:

Der erste Buchstabe der Variable steht für den Typ des in der Variable gespeicherten Wertes. Dabei bezeichnen folgende Buchstaben die entsprechenden Datentypen (in Anlehung an das Tutorial.pdf von Sun):

{| border="1"
|'''''Buchstabe'''''
|'''''Bedeutung'''''
|-
|a
|Struktur (Structure)
|-
|b
|Bool'sch (WAHR oder FALSCH)
|-
|e
|Aufzählung (Enumeration). Diese Variable kann nur einen begrenzten Satz von Werten enthalten.
|-
|f
|Fließkomma-Zahl (3.402823 x 1038 bis 1.401298 x 10-45. Eine einzelne Variable kann bis zu 4 Bytes umfassen) "Double" (doppelte Genauigkeit, 1.79769313486232 x 10308 bis 4.94065645841247 x 10-324. Eine Double-Variable kann bis zu 8 Bytes umfassen) Währung (-922337203685477.5808 bis +922337203685477.5807 ebenfalls 8 Byte umfassend)
|-
|m
|Feld (Array) (aka Sequenz aka Matrix)
|-
|n
|Integer (-32768 to 32767.) oder Long (-2147483648 and 2147483647).
|-
|o
|Objekt, Service oder Interface
|-
|s
|Text (String) (Eine String-Variable kann bis zu 65535 Unicode-Zeichen enthalten).
|-
|x
|Schnittstelle (Interface), um anzuzeigen, dass nur Methoden einer bstimmten Schnittstelle eines Objekts verwendet werden.
|-
|v
|Variant, irgend ein Typ
|-
|}

Benutzen Sie lange, beschreibende Variablennamen unter Verwendung von CamelCase (Groß-Klein-Schreibung).

{| border="1"
|'''Achtung:'''
|Bei benutzerdefinierten OpenOffice.org Basic-Variablen spielt die Groß-/Kleinschreibunge keine Rolle. Bei UNO-API-Konstanten aber sehr wohl!
|}

Ausnahmen von der Regel, lange Namen zu verwenden, sind Index-Variablen (meist i, j oder k), sowie Strings (meist als s bezeichnet).

Bearbeiten Sie nun die sub HelloWorld, so dass der Code ungefähr wie im folgenden aussieht und führen Sie sie aus:

<code>[oobas]
sub HelloWorld
dim i as integer 'This line is optional
for i = 0 to 2
'These lines are indented for ease of reading only
'all your code should be like this for lonog time survival
msgbox "Hello World " & i
next i
end sub
</code>

Mehr Infos zur Verwendung von Variablen erhalten Sie in der Online-Hilfe unter "Variablen benutzen" (???)

= Die OpenOffice.org API =

Dieser Abschnitt beginnt mit einem Beispiel. Anschließend wird das Beispiel erläutert.

Versuchen Sie den folgenden Code in Dokumenten unterschiedlichen Typs auszuführen:

<code>[oobas]
sub main
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
msgbox fnWhichComponent(thisComponent)
end sub

function fnWhichComponent(oDoc) as string
if HasUnoInterfaces(oDoc, "com.sun.star.lang.XServiceInfo") then
if thisComponent.supportsService ("com.sun.star.text.GenericTextDocument") then
fnWhichComponent = "Text"
elseif thisComponent.supportsService("com.sun.star.sheet.SpreadsheetDocument") then
fnWhichComponent = "Spreadsheet"
elseif thisComponent.supportsService("com.sun.star.presentation.PresentationDocument") then
fnWhichComponent = "Presentation"
elseif thisComponent.supportsService("com.sun.star.drawing.GenericDrawingDocument") then
fnWhichComponent = "Drawing"
else
fnWhichComponent = "Oops current document something else"
end if
else
fnWhichComponent = "Not a document"
end if
End function
</code>

== Namenskonventionen für Subroutinen ==
im obigen Beispiel beginnt die Benutzer-definierte Funktion mit den Buchstaben "fn". Diese Konvention (an die sich der ursprüngliche Autor hält) kennzeichnet eine Funktion als Benutzer-definiert. Entsprechend beginnt eine Benutzer-definierte Subroutine mit "sub". Diese im Folgenden benutzten Konventionen sollen Ihnen als Anfängern helfen, Benutzer-definierte von eingebauten Routinen/Funktionen zu unterscheiden.

== Einführung in die OpenOffice.org API ==

In diesem Abschnitt werden folgende Begriffe erläutert:

* Interface (Schnittstelle)
* Modul
* Service (Dienst)
* Methode
* Property (Eigenschaft)

Den Unterschied zwischen einer Schnittstelle und einem Service zu kennen, ist zwar nicht unbedingt Voraussetzung zum Programmieren unter OpenOffice.org, aber es hilft, die Dokumentation zu verstehen, und auch bei der Introspektion. Möglicherweise werden Sie den folgenden Abschnitt mindestens zwei mal lesen müssen!

Eine Schnittstelle ist eine ''Definition'' eines Satzes von Methoden (und ihren Argumenten), die ein Dienst, der diese Schnittstelle implementiert, enthalten muss.

Schnittstellen werden aus Gründen der Namensgebung zu '''Modulen''' gruppiert. Alle Schnittstellen (und Dienste) beginnen mit <tt>com.sun.star</tt>, gefolgt vom Modul-Namen, dann kommt der Name der Schnittstelle (oder des Dienstes).

Beispielsweise bieten die meisten Dienste die Schnittstelle <tt>com.sun.star.beans.XPropertySet</tt>. Diese Schnittstelle ist im Modul <tt>beans</tt> gespeichert und ermöglicht Zugriff auf die Eigenschaften (Properties) eines Dienstes. Eine '''Eigenschaft''' ist ein Wert, eine '''Methode''' ist dagegen eine Aktion.

Ein OpenOffice.org-Objekt kann viele Dienste enthalten.

Ein OpenOffice.org-Objekt kann einen Dienst enthalten, der eine Schnittstelle implementiert, in welcher eine Methode beschreibt, dass ein anderes OpenOffice.org-Objekt zurückgegeben wird.

== Introspektion ==

'''HasUnoInterfaces''' ist eine OpenOffice.org-Basic-Funktion zur Introspektion. Informieren Sie sich über [http://www.oooforum.org/forum/viewtopic.phtml?t=7068 Introspektion in anderen Sprachen].

<tt>HasUnoInterfaces</tt> gibt <code>true</code> zurück, wenn beim spezifizierten Objekt alle spezifizierten Schnittstellen verfügbar sind.

Die meisten OpenOffice.org-Objekte enthalten die Methode '''supportsService''' weil sie die Schnittstelle <code>com.sun.star.lang.XServiceInfo</code> enthalten.

Im obigen Beispiel prüft <tt>HasUnoInterfaces</tt>, ob das aktuelle Dokument die Schnittstelle <tt>com.sun.star.lang.XServiceInfo</tt> implementiert, da andernfalls die Methode <tt>supportsService</tt> fehlen würde. Der Aufruf dieser Methode würde in diesem Fall einen Laufzeitfehler verursachen.

<tt>supportsService</tt> ist eine Methode, die den Wert <code>true</code> zurückgibt, wenn der spezifizierte Service verfügbar ist. Das obige Beispiel prüft das Vorhandensein eines Service, um so den Typ des aktuell aktiven Dokuments zu bestimmen.

== X-Ray tool ==
Die Benutzung von <tt>HasUnoInterfaces</tt> und <tt>supportsService</tt> reicht aus, um sich zur Laufzeit über ein Objekt zu informieren, aber zum Lernen eignet sich das [http://ooomacros.org/dev.php#101416 X-Ray tool von Bernard Marcelly] viel besser. Laden Sie das ZIP-File herunter, entpacken Sie es und öffnen Sie das enthaltene Dokument mit OpenOffice.org. Befolgen Sie anschließend die Installationsanweisungen.

Das '''X-Ray tool''' verlangt bei der Konfiguration eine lokale Kopie des OpenOffice.org SDK. Laden Sie es von [http://www.openoffice.org/dev_docs/source/sdk/ hier] herunter und entpacken Sie es.

Nun können Sie die beiden auskommentierten Zeilen des obigen Beispiels entkommentieren (den Apostroph entfernen):

<code>[oobas]
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
</code>

Führen Sie das Makro dann erneut aus.

Ab Xray Version 5 heißt das Kommando einfach '''xray'''.

'''BasicLibraries''' ist ein OpenOffice.org-Basic-Befehl, der ein Objekt zurückgibt, mit dem man auf die OpenOffice.org Bibliotheken zugreifen kann. Die Methode <tt>loadLibrary</tt> macht die Routinen aus dieser Bibliothek verfügbar.

<tt>xray.xray</tt> spezifiziert die Subroutine <tt>xray</tt> im Modul <tt>xray</tt> in dieser Bibliothek, <tt>thisComponent</tt> ist das Objekt, das an xray zur Introspektion übergeben wird.

Um mit einem bestimmten Objekt zu arbeiten erfordert häufig, dieses Objekt zu finden oder zu erzeugen, indem man mit <tt>StarDesktop</tt> oder <tt>thisComponent</tt> beginnt.

== Desktop, Dokumente, Selektionen ==
<tt>StarDesktop</tt> und <tt>ThisComponent</tt> sind OpenOffice.org-Basic-Befehle, die sich auf die Applikation bzw. das aktuell aktive Dokument beziehen.

Im Unterschied zu Microsoft Office ist OpenOffice.org eine Anwendung mit unterschiedlichen Komponenten. Beim Ausführen von Code möchte man häufig wissen, welche Komponente aktuell aktiv ist. Der obige Code zeigt eine Möglichkeit, dies zu überprüfen.

StarDesktop bezieht sich auf einen konzeptuellen Desktop (der historisch tatsächlich mal existiert hat) und meint de facto die Anwendung OpenOffice.org.

== Neue Dokumente erzeugen ==
Um ein neues Text-Dokument zu erzeugen:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/swriter", "_blank", 0, Array())
</code>
Um ein neues Tabellen-Dokument zu erzeugen:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/scalc", "_blank", 0, Array())
</code>
Ein sinnvoller Ansatz wäre, eine einfache Funktion zu schreiben:

<code>[oobas]
function fnNewDoc(sDocType as string)
fnNewDoc = StarDesktop.loadComponentFromURL("private:factory/" & sDocType , "_blank", 0, Array())
end function
</code>
Dann könnte man neue Dokumente ganz einfach erzeugen:

<code>[oobas]
oDoc = fnNewDoc("swriter")
oDoc = fnNewDoc("scalc")
oDoc = fnNewDoc("simpress")
oDoc = fnNewDoc("sdraw")
oDoc = fnNewDoc("smath")
</code>
Siehe http://api.openoffice.org/docs/common/ref/com/sun/star/frame/XComponentLoader.html .

== Ein bestehendes Dokument öffnen ==
Im folgenden Beispiel sehen Sie, wie Sie eine Datei öffnen können. OpenOffice.org URLs sind in [[DE: URL Grundlagen]] erläutert.

<code>[oobas]
sFile = "C:\Documents and Settings\danny\Desktop\MyCalc.sxc" ' Windows
sFile = "/home/danny/Desktop/MyCalc.sxc" ' Linux
sURL = ConvertToURL(sFile)
oDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
</code>
Auch hier könnte eine einfache Funktion das Schreiben verkürzen:

<code>[oobas]
function fnOpenDoc(sFile)
sURL = ConvertToURL(sFile)
fnOpenDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
end function
</code>
Beispiele für Aufrufe:

<code>[oobas]
oDoc = fnOpenDoc("C:\Documents and Settings\danny\Desktop\MyCalc.sxc") ' Windows
oDoc = fnOpenDoc("/home/danny/Desktop/MyCalc.sxc") ' Linux
</code>

== Die aktuelle Selektion ==
Häufig werden Sie eine Funktion schreiben wollen, die etwas mit dem aktuell selektierten Bereich anstellt. <tt>ThisComponent</tt> enthält die Methode <tt>getCurrentSelection</tt>. Da viele unterschiedliche Objekte selektiert sein könnten, werden Sie zuerst prüfen wollen, ob das selektierte Objekt über den Dienst verfügt, der die Methode enthält, mit der Sie das Objekt bearbeiten wollen.

Editieren Sie die Subroutine main im nachfolgenden Code und führen Sie sie mehrfach in einem Textdokument aus, wobei Sie unterschiedliche Objekte selektieren. (Um mehr als einen Textblock zu selektieren, betätigen Sie die '''Strg'''-Taste).

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
'xray.xray oCurSelection
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
msgbox "There are " & oCurSelection.getCount() & _
" selections in the current text document."
end if
end if
end sub
</code>
Wenn nichts selektiert ist, beträgt die Anzahl der Selektionen eins (nämlich der Einfügepunkt), wenn ein Textblock selektiert ist, beträgt die Anzahl ebenfalls eins, wenn zwei Textblöcke selektiert sind, beträgt sie drei: der Einfügepunkt sowie die beiden selektierten Textblöcke.

Übung 1: Modifizieren Sie den obigen Code so, dass er mit selektierten Zellbereichen in einem Tabellendokument funktioniert.

Frage 1: Wie hoch ist die Anzahl der Selektionen, wenn zwei Zellblöcke selektiert sind?

==Properties==
Wenn Sie die Zeile <tt>'xray.xray oCurSelection</tt> entkommentieren, so dass xray läuft, sehen Sie, dass das Objekt, worauf <tt>oCurSelection</tt> zeigt, eine "Property" namens <tt>Count</tt> besitzt, mit einer Beschreibung "pseudo-prop, read only". In OpenOffice.org Basic könnten Sie <tt>oCurSelection.count</tt> schreiben, da dies aber in keiner anderen Sprache, mit der Sie auf die OpenOffice.org API zugreifen können, möglich ist, werde ich versuchen, in diesem Wiki nur über Methoden zuzugreifen. (Möglicherweise vergesse ich das auch das eine oder andere Mal).

Das nächste Beispiel zeigt, wie man einen Property-Wert für die aktuellen Selektionen ändert.

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
nCount = oCurSelection.Count
'xray.xray oCurSelection.getByIndex(0)
'Warnung: Am Einfügepunkt wird die selbe Aktion zwei mal angewandt -
'das macht in diesem Fall nichts, kann aber durchaus problematisch werden.
for i = 0 to nCount - 1
oCurSelection.getByIndex(i).setPropertyValue("CharStyleName", "Strong Emphasis")
next
end if
end if
end sub
</code>

In OpenOffice.org Basic kann man die Zuweisung auch abkürzen:

<code>[oobas]
oCurSelection(i).CharStyleName = "Strong Emphasis"
</code>
Hier in diesem Wiki versuche ich, sowohl zur Indexierung als auch zur Zuweisung von Properties die vollständigen Methoden zu verwenden. Dadurch kann der Code leichter in andere Sprachen portiert werden und es hilft Ihnen auch, zu verstehen, was vor sich geht (nochmal: Bitte um Entschuldigung, wenn ich mal von dieser Regel abweiche, weil ich es eigentlich nicht gewohnt bin)

Übung 2: Schreiben Sie den obigen Code so um, dass die Warnung entfernt werden kann.

Siehe [[DE:Aktuelle Selektion]] ([[ Current selection]]).

=Iterativer Zugriff auf untergeordnete Objekte ( berechtigungsgesteuerte Auflistung )=
Manchmal ist zum Zugriff auf ein gewünschtes Objekt eine Enumeration (Auflistung) nötig. Beispielsweise ein Satz innerhalb eines Dokumentes oder innerhalb einer Auswahl.

Wenn innerhalb eines OpenOffice-Writer Dokuments eine Text selektiert wird, können die Methoden <tt>thisDocument.getText()</tt> und <tt>thisComponent.getCurrentSelection().getByIndex(i)</tt> verwand werden.
com.sun.star.text.TextRange ist die Schnittstelle (Interface): com.sun.star.container.XContentEnumerationAccess, it is possible to create an enumeration of the paragraphs for the current document or for a particular selection.

<code>[oobas]
' Create enumeration object
oTextElementEnum = thisComponent.getText().createEnumeration()
'or thisComponent.getCurrentSelection().getByIndex(i).createEnumeration()

' loop over all text elements
while oTextElementEnum.hasMoreElements()
oTextElement = oTextElementEnum.nextElement
if oTextElement.supportsService("com.sun.star.text.TextTable") then
MsgBox "The current block contains a table."
end if
if oTextElement.supportsService("com.sun.star.text.Paragraph") then
MsgBox "The current block contains a paragraph."
end if
wend
</code>
Aufgabe 3: Erweitere das obige Beispiel so, das eine MessageBox aller Worte des Schrifttyps "bold" zeigt .

=Named access=
Some objects provide named access to a particular type of subordinate object, some others indexed access, and some both named and indexed access.

For example if the current document in OpenOffice.org is a spreadsheet then to access a particular sheet can be done by index access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByIndex(0)
</code>
or named access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByName("Sheet1")
</code>
To check if an object with a particular name already exists use <tt>hasByName</tt>, for example:

<code>[oobas]
if thisComponent.getSheets.hasByName("Sheet1") then
</code>
To loop through all the available object names can be done like:

<code>[oobas]
mNames = thisComponent.getSheets.getElementnames
for i = lbound(mNames) to ubound(mNames)
msgbox mNames(i)
next
</code>

Some named subordinate objects also provide the interface: com.sun.star.container.XNameContainer. This interface defines that such objects should have the following methods: <tt>insertByName</tt>, <tt>replaceByname</tt> and <tt>removeByName</tt>.

E.g.

<code>[oobas]
thisComponent.getSheets.insertByName("NewSheet")
</code>

=Create new objects=
Some objects have services which implement interfaces to provide specific methods for creating a particular type of object.

For example if the current document is a Writer document then <tt>thisComponent.getText</tt> is an object that provides the service com.sun.star.text.Text which implements the interface com.sun.star.text.XSimpleText which defines the methods <tt>createTextCursor</tt> and <tt>createTextCursorByRange</tt>. Both of these methods create a text cursor for accessing the text of the document. These cursors are quite independent of the view cursor . The view cursor is visible on the screen and is manipulated by the user (and can be manipulated by program control), where as a text cursor is not visible on the screen and is solely used by program control. The following code snippet demonstrates creating a new text cursor, such that it starts at the same location as the viewCursor and is then moved independent of the view cursor.

<code>[oobas]
oVC = thisComponent.getCurrentController.getViewCursor
oCursor = oVC.getText.createTextCursorByRange(oVC)
oCursor.gotoStartOfSentence(false)
oCursor.gotoEndOfSentence(true)
msgbox oCursor.getString
</code>

Some objects are context dependent and get created using the method <tt>createInstance</tt> which is defined in the interface com.sun.star.lang.XMultiServiceFactory. For example to add a rectangle to the first page of a drawing document:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
dim aSize as new com.sun.star.awt.Size

aPoint.x = 1000
aPoint.y = 1000

aSize.Width = 10000
aSize.Height = 10000

oRectangleShape = thisComponent.createInstance("com.sun.star.drawing.RectangleShape")
oRectangleShape.Size = aSize
oRectangleShape.Position = aPoint

thisComponent.getDrawPages.getByIndex(0).add(oRectangleShape)
</code>

This example also uses UNO structs see below for more information on UNO stucts.

Some objects are context independent to create these objects use the OpenOffice.org Basic command createUnoService. For example to create the equivalent to StarDesktop:

<code>[oobas]
oDesktop = createUnoService("com.sun.star.frame.Desktop")
</code>

The process that I use to determine how to access or create an object is as follows:

Does the object already exist if so I should be able to access it from something like <tt>thisComponent</tt>.

Will the new object belong to another object, if so does the owner have a specific method for creating the object, if so use it.

The new object will belong to another object, but that object doesn't provide a specific method for creating it, but does provide <tt>createInstance</tt>. If the object doesn't provide <tt>createInstance</tt> are you sure you are using the correct object, or is it context independent.

I have found working out how to create an object to be quite difficult with existing documentation so I hope that this document/wiki will eventually make this clear.

==UNO structs==
UNO structures can be declared using the OpenOffice.org Basic command <tt>dim</tt>:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
</code>
Or by using the OpenOffice.org Basic command <tt>createUnoStruct</tt>:

<code>[oobas]
aPoint = createUnoStruct("com.sun.star.awt.Point")
</code>

{| border="1"
|'''Note:'''
|When declaring UNO structs case is important. Note that everything upto the name of the struct is lowercase, and that the name of the struct is in TitleCase.
|}

==Creating Listeners and Handlers==
Through the user interface it is possible to assign macros to some events:

OpenOffice.org versions 1.1.x: '''Tools > Configure… > Events'''.

OpenOffice.org versions 1.9.x and above: '''Tools > Customize… > Events'''.

It is also possible to assign macros to a wider range of events using the OpenOffice.org Basic command CreateUnoListener. This same command is used for creating both listeners and handlers. A listener checks for an event and always allows other listeners to respond to the event as well. A handler listens for an event, and can optionally consume the event so that other listeners don't get to act on it.

The following example creates a keyHandler:

<code>[oobas]
global IannzExampleKeyHandler

sub SetupKeyHandler
oController = thisComponent.currentController
IannzExampleKeyHandler = CreateUnoListener("KeyHandler_","com.sun.star.awt.XKeyHandler")
oController.addKeyHandler(IannzExampleKeyHandler) ' Register the listener
end sub

sub RemoveKeyHandler
thisComponent.currentController.removeKeyHandler(IannzExampleKeyHandler)
end sub

sub KeyHandler_disposing
end sub

function KeyHandler_keyReleased(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyReleased = False
end function

function KeyHandler_keyPressed(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyPressed = false 'Let other listeners handle the event
if oKeyEvent.modifiers = com.sun.star.awt.KeyModifier.MOD2 then 'Control key was pressed
if oKeyEvent.keyCode = com.sun.star.awt.Key.Q then
msgbox "Alt + Q was pressed"
KeyHandler_keyPressed = true 'Don't let other listeners process this event
end if
end if
end function
</code>
A variable declared as global keeps its value even after the macro exits. In this case we want to be able to use this variable later to remove the handler. As variables declared globally could be used in other libraries to try and avoid conflict I start all my global variables with Iannz my registered name for the OpenOffice.org web site.

<tt>sub SetupKeyHandler</tt> sets up the handler. The first parameter to CreateUnoListener is the staring name for the methods that will be called when that type of event occurs in this example .<tt>"KeyHandler_"</tt>.

The second parameter is the name of the interface for the listener or handler, "com.sun.star.awt.XKeyHandler". The name is case sensitive, everything up to and including the module name is always lowercase, the name of the interface always starts with "X" and the remainder is in TitleCase.

Use the SDK to find out what methods the interface must supply. You must supply routines for all of these methods even if you don't intend to use them. You also need to supply a disposing method. The names of these routines start with the string given in the first parameter to CreateUnoListener , in this example <tt>"KeyHandler_"</tt>.

Thus in the example there is <tt>KeyHandler_disposing</tt> and <tt>KeyHandler_keyReleased</tt> which don't actually do anything but are required, and <tt>KeyHandler_keyPressed</tt> which actually does the job.

<tt>sub RemoveKeyHandler</tt> demonstrates how to remove the handler.

=OpenOffice.org constants=
The above example uses OpenOffice.org constants.

E.g. com.sun.star.awt.KeyModifier.MOD2

OpenOffice.org constants are case sensitive. Everything up to and including the module name is always lowercase. The constant group is in TitleCase. The actual constant name is always UPPERCASE.

Programmers not using OpenOffice.org Basic may not have access to these constants.

=Using the recorder=
See [[ The OpenOffice.org recorder and UNO dispatch calls]] section for a discussion on recording UNO Dispatch commands versus writing API calls.

[[Category:Basic:Tutorials]]

DE/Makro Basic Tutorial

2006-09-06T01:31:26Z

Global667: /* Iterativer Zugriff auf untergeordnete Objekte (berechtigungsgesteuerte Auflistung) */

[[Category:de.openoffice.org|Makro Basic Tutorial]]

{| cellspacing=0 cellpadding=5 style="border: 1px solid black;"
| bgcolor=orange colspan=2 |'''Achtung, work in progress'''
Dieses Dokument wird gerade übersetzt, wer mag, darf auch gerne helfen.
|-
|'''Arbeitstitel:''' || "Einführung: Basic für OOo-Erweiterungen"
|-
|'''Originaldokument:''' || [[Extensions_development_basic]] 
|-
|'''Ursprünglicher Autor:''' || Ian Laurenson
|-
| offene Fragen: || sind mit ??? gekennzeichnet
|}

Diese Seite soll Ihnen eine Einführung in das Schreiben von Makros mit OpenOffice.org Basic geben. Grundkenntnisse im Programmieren werden vorausgesetzt. Bitte fühlen Sie sich frei, diese Seite zu editieren, um sie lesbarer zu machen. Ich hoffe, das Sie Ihnen von Nutzen sein wird.

Wenn Sie bereits mit den Grundlagen vertraut sind, können Sie sich auch direkt im KochBuch ([[CookBook]]) Wrapper (Hüllfunktionen ???) und Beispiele anschauen.

= Wohin schreibe ich den Code? =

Der Basic-Code wird bei OpenOffice.org in '''Modulen''' gespeichert, die in '''Bibliotheken''' zusammengefasst sind.

Eine Bibliothek kann
* '''allgemein''', also für die gesamte (Netzwerk-) Installation verfügbar sein ("OOo Makros und Dialoge")
* nur für den aktuellen '''Benutzer''' verfügbar sein ("Meine Makros und Dialoge")
* in einem '''Dokument''' oder in einer Vorlage abgelegt sein, so dass ihr Code nur zur Verfügung steht, wenn das Dokument geöffnet ist.
Bibliotheken, die nicht in einem Dokument abgelegt sind (also allgemein oder für den aktuellen Benutzer verfügbare Bibliotheken) werden im Folgenden als ''OpenOffice.org Bibliotheken'' zusammengefasst.

Der physische Speicherort für diese OpenOffice.org Bibliotheken wird unter '''Extras > Optionen… > OpenOffice.org > Pfade > BASIC''' festgelegt.

{| border="1"
|'''Anmerkung:'''
|Hüten Sie sich, Bibliotheken auf Dateisystem-Ebene zu verschieben oder zu kopieren. Benutzen Sie stattdessen den Dialog "Makros verwalten" oder den Paket-Manager
|}

Module in Bibliotheken können maximal 64kb groß sein. Eine Bibliothek kann bis zu 16 000 Module enthalten. Weitere Infos finden Sie in der Online-Hilfe unter "Module und Bibliotheken" (???).

= Die Entwicklungsumgebung (IDE) =

Öffnen Sie die Entwicklungsumgebung:
* in OOo 1.1.x unter '''Extras > Makros > Makro ...'''
* in OOo 1.9.x und höher unter ''' Extras > Makros > Makros verwalten > OpenOffice.org Basic...'''

Zum Einstieg benutzen wir das "Modul1" aus der Bibliothek "Standard" des aktuellen Benutzers:

Geben Sie einen Namen für das neue Makro ein: "HelloWorld"

Wählen Sie die Option '''Standard''' im Auswahlfeld "Makro aus:"

Klicken Sie auf '''Neu'''

Jetzt sollten Sie etwa folgendes sehen:

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub

Sub HelloWorld

End Sub
</code>

Der Cursor sollte am Anfang der Zeile <tt>Sub HelloWorld</tt> stehen.

{| border="1"
|'''Achtung:'''
|Das geöffnete IDE-Fenster ist sowohl über das Menü im OpenOffice.org-Fenster als auch über die Programmleiste des Betriebssystems erreichbar.
|}

= Eingeben von Programm-Code =

Löschen Sie folgende Zeilen:

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub
</code>

Schreiben Sie unterhalb der Zeile "Sub HelloWorld": <tt>msgbox "Hello World!"</tt>, so dass es in etwa so aussieht:

<code>[oobas]
Sub HelloWorld
msgbox "Hello World!"
End Sub
</code>

{| border="1"
|'''Achtung:'''
|Die IDE beherrscht zwar keine "code completion"(->dt.Auto-Vervollständigung), also die Fähigkeit eines Editors den Text automatisch zu vervollständigen, um den Schreibprozess zu beschleunigen, während der Eingabe, verfügt aber über eine kontext-sensitive Hilfe, wenn Sie während der Eingabe F1 oder "Hilfe" drücken oder der Cursor in einem Befehl steht. Bei OpenOffice.org Basic-Befehlen wird die Groß- und Kleinschreibung nicht unterschieden. So sind die Eingaben msgbox, MSGBOX oder Msgbox äquivalent. Strings (Textvariablen) werden in doppelte Anführrungszeichen eingeschlossen.
|-
|}

= Den Code ausführen =

Hierfür gibt es mehrere Möglichkeiten:

* direkt aus der IDE: das Symbol '''Ausführen''' (das 3. Symbol in der 2. Leiste) ruft das ERSTE Makro des aktuellen Moduls auf.
* aus dem Menü "Extras":
** (Version 1.1.x) '''Extras > Makros > Makro…''';
** (Version 1.9.x und höher) '''Extras > Makro > Makro auführen…'''
* Dem Makro ein Tastaturkürzel zuweisen (todo).
* Dem Makro einen Menüeintrag zuweisen (todo).
* Dem Makro ein Symbolleisten-Symbol zuweisen (todo).
* Ein Kontroll-Element in einem Dokument erstellen (todo).
* Das Makro einem Ereignis zuweisen (todo)

Führen Sie für den Anfang die "HelloWorld"-Subroutine aus, indem Sie auf das '''Ausführen'''-Symbol klicken. Ein kleiner Dialog mit dem Titel "soffice" und dem Text "Hello World" sollte aufpoppen.

= Speichern des Code =

Der Code wird immer automatisch gespeichert, wenn sein Container gespeichert wird. Wenn das Modul also in einer (allgemeinen oder benutzerspezifischen) OpenOffice.org-Bibliothek enthalten ist, wird es beim Schließen der Anwendung OpenOffice.org gespeichert. Entsprechend werden Dokument-interne Bibliotheken biem Speichern des Dokuments mit-gesichert.

Auf der Standard-Symbolleiste der IDE (normalerweise die oberste Symbolleiste) finden Sie ein Symbol "Speichern". Befindet sich der Code in einem Dokument oder einer Vorlage, dann speichert der Klick auf dieses Symbol das gesamte Dokument. Handelt es sich dagegen um eine OpenOffice.org-Bibliothek, wird nur die aktuelle Bibliothek gespeichert.

= Variablen =

Bei Variablen kann durch <tt>Option Explicit</tt> zu Beginn des Moduls die explizite Deklaration erzwungen werden. Zu Sinn und Unsinn des Deklarierens von Variablen lesen Sie [http://www.oooforum.org/forum/viewtopic.phtml?t=5845 diese Diskussion].

In dieser Diskussion vertritt der ursprüngliche Autor dieses Wiki-Beitrags die Position, dass Variablen immer deklariert werden sollten. Mittlerweile hat er seine Meinung geändert. Kurz: es ist eine Frage des persönlichen Geschmacks. Unabhängig davon sollten nach Auffassung des ursprünglichen Autors Variablen nach folgener Konvention benannt werden, die auch bei den Beispielen aus diesem Wiki verwendet wurde:

Der erste Buchstabe der Variable steht für den Typ des in der Variable gespeicherten Wertes. Dabei bezeichnen folgende Buchstaben die entsprechenden Datentypen (in Anlehung an das Tutorial.pdf von Sun):

{| border="1"
|'''''Buchstabe'''''
|'''''Bedeutung'''''
|-
|a
|Struktur (Structure)
|-
|b
|Bool'sch (WAHR oder FALSCH)
|-
|e
|Aufzählung (Enumeration). Diese Variable kann nur einen begrenzten Satz von Werten enthalten.
|-
|f
|Fließkomma-Zahl (3.402823 x 1038 bis 1.401298 x 10-45. Eine einzelne Variable kann bis zu 4 Bytes umfassen) "Double" (doppelte Genauigkeit, 1.79769313486232 x 10308 bis 4.94065645841247 x 10-324. Eine Double-Variable kann bis zu 8 Bytes umfassen) Währung (-922337203685477.5808 bis +922337203685477.5807 ebenfalls 8 Byte umfassend)
|-
|m
|Feld (Array) (aka Sequenz aka Matrix)
|-
|n
|Integer (-32768 to 32767.) oder Long (-2147483648 and 2147483647).
|-
|o
|Objekt, Service oder Interface
|-
|s
|Text (String) (Eine String-Variable kann bis zu 65535 Unicode-Zeichen enthalten).
|-
|x
|Schnittstelle (Interface), um anzuzeigen, dass nur Methoden einer bstimmten Schnittstelle eines Objekts verwendet werden.
|-
|v
|Variant, irgend ein Typ
|-
|}

Benutzen Sie lange, beschreibende Variablennamen unter Verwendung von CamelCase (Groß-Klein-Schreibung).

{| border="1"
|'''Achtung:'''
|Bei benutzerdefinierten OpenOffice.org Basic-Variablen spielt die Groß-/Kleinschreibunge keine Rolle. Bei UNO-API-Konstanten aber sehr wohl!
|}

Ausnahmen von der Regel, lange Namen zu verwenden, sind Index-Variablen (meist i, j oder k), sowie Strings (meist als s bezeichnet).

Bearbeiten Sie nun die sub HelloWorld, so dass der Code ungefähr wie im folgenden aussieht und führen Sie sie aus:

<code>[oobas]
sub HelloWorld
dim i as integer 'This line is optional
for i = 0 to 2
'These lines are indented for ease of reading only
'all your code should be like this for lonog time survival
msgbox "Hello World " & i
next i
end sub
</code>

Mehr Infos zur Verwendung von Variablen erhalten Sie in der Online-Hilfe unter "Variablen benutzen" (???)

= Die OpenOffice.org API =

Dieser Abschnitt beginnt mit einem Beispiel. Anschließend wird das Beispiel erläutert.

Versuchen Sie den folgenden Code in Dokumenten unterschiedlichen Typs auszuführen:

<code>[oobas]
sub main
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
msgbox fnWhichComponent(thisComponent)
end sub

function fnWhichComponent(oDoc) as string
if HasUnoInterfaces(oDoc, "com.sun.star.lang.XServiceInfo") then
if thisComponent.supportsService ("com.sun.star.text.GenericTextDocument") then
fnWhichComponent = "Text"
elseif thisComponent.supportsService("com.sun.star.sheet.SpreadsheetDocument") then
fnWhichComponent = "Spreadsheet"
elseif thisComponent.supportsService("com.sun.star.presentation.PresentationDocument") then
fnWhichComponent = "Presentation"
elseif thisComponent.supportsService("com.sun.star.drawing.GenericDrawingDocument") then
fnWhichComponent = "Drawing"
else
fnWhichComponent = "Oops current document something else"
end if
else
fnWhichComponent = "Not a document"
end if
End function
</code>

== Namenskonventionen für Subroutinen ==
im obigen Beispiel beginnt die Benutzer-definierte Funktion mit den Buchstaben "fn". Diese Konvention (an die sich der ursprüngliche Autor hält) kennzeichnet eine Funktion als Benutzer-definiert. Entsprechend beginnt eine Benutzer-definierte Subroutine mit "sub". Diese im Folgenden benutzten Konventionen sollen Ihnen als Anfängern helfen, Benutzer-definierte von eingebauten Routinen/Funktionen zu unterscheiden.

== Einführung in die OpenOffice.org API ==

In diesem Abschnitt werden folgende Begriffe erläutert:

* Interface (Schnittstelle)
* Modul
* Service (Dienst)
* Methode
* Property (Eigenschaft)

Den Unterschied zwischen einer Schnittstelle und einem Service zu kennen, ist zwar nicht unbedingt Voraussetzung zum Programmieren unter OpenOffice.org, aber es hilft, die Dokumentation zu verstehen, und auch bei der Introspektion. Möglicherweise werden Sie den folgenden Abschnitt mindestens zwei mal lesen müssen!

Eine Schnittstelle ist eine ''Definition'' eines Satzes von Methoden (und ihren Argumenten), die ein Dienst, der diese Schnittstelle implementiert, enthalten muss.

Schnittstellen werden aus Gründen der Namensgebung zu '''Modulen''' gruppiert. Alle Schnittstellen (und Dienste) beginnen mit <tt>com.sun.star</tt>, gefolgt vom Modul-Namen, dann kommt der Name der Schnittstelle (oder des Dienstes).

Beispielsweise bieten die meisten Dienste die Schnittstelle <tt>com.sun.star.beans.XPropertySet</tt>. Diese Schnittstelle ist im Modul <tt>beans</tt> gespeichert und ermöglicht Zugriff auf die Eigenschaften (Properties) eines Dienstes. Eine '''Eigenschaft''' ist ein Wert, eine '''Methode''' ist dagegen eine Aktion.

Ein OpenOffice.org-Objekt kann viele Dienste enthalten.

Ein OpenOffice.org-Objekt kann einen Dienst enthalten, der eine Schnittstelle implementiert, in welcher eine Methode beschreibt, dass ein anderes OpenOffice.org-Objekt zurückgegeben wird.

== Introspektion ==

'''HasUnoInterfaces''' ist eine OpenOffice.org-Basic-Funktion zur Introspektion. Informieren Sie sich über [http://www.oooforum.org/forum/viewtopic.phtml?t=7068 Introspektion in anderen Sprachen].

<tt>HasUnoInterfaces</tt> gibt <code>true</code> zurück, wenn beim spezifizierten Objekt alle spezifizierten Schnittstellen verfügbar sind.

Die meisten OpenOffice.org-Objekte enthalten die Methode '''supportsService''' weil sie die Schnittstelle <code>com.sun.star.lang.XServiceInfo</code> enthalten.

Im obigen Beispiel prüft <tt>HasUnoInterfaces</tt>, ob das aktuelle Dokument die Schnittstelle <tt>com.sun.star.lang.XServiceInfo</tt> implementiert, da andernfalls die Methode <tt>supportsService</tt> fehlen würde. Der Aufruf dieser Methode würde in diesem Fall einen Laufzeitfehler verursachen.

<tt>supportsService</tt> ist eine Methode, die den Wert <code>true</code> zurückgibt, wenn der spezifizierte Service verfügbar ist. Das obige Beispiel prüft das Vorhandensein eines Service, um so den Typ des aktuell aktiven Dokuments zu bestimmen.

== X-Ray tool ==
Die Benutzung von <tt>HasUnoInterfaces</tt> und <tt>supportsService</tt> reicht aus, um sich zur Laufzeit über ein Objekt zu informieren, aber zum Lernen eignet sich das [http://ooomacros.org/dev.php#101416 X-Ray tool von Bernard Marcelly] viel besser. Laden Sie das ZIP-File herunter, entpacken Sie es und öffnen Sie das enthaltene Dokument mit OpenOffice.org. Befolgen Sie anschließend die Installationsanweisungen.

Das '''X-Ray tool''' verlangt bei der Konfiguration eine lokale Kopie des OpenOffice.org SDK. Laden Sie es von [http://www.openoffice.org/dev_docs/source/sdk/ hier] herunter und entpacken Sie es.

Nun können Sie die beiden auskommentierten Zeilen des obigen Beispiels entkommentieren (den Apostroph entfernen):

<code>[oobas]
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
</code>

Führen Sie das Makro dann erneut aus.

Ab Xray Version 5 heißt das Kommando einfach '''xray'''.

'''BasicLibraries''' ist ein OpenOffice.org-Basic-Befehl, der ein Objekt zurückgibt, mit dem man auf die OpenOffice.org Bibliotheken zugreifen kann. Die Methode <tt>loadLibrary</tt> macht die Routinen aus dieser Bibliothek verfügbar.

<tt>xray.xray</tt> spezifiziert die Subroutine <tt>xray</tt> im Modul <tt>xray</tt> in dieser Bibliothek, <tt>thisComponent</tt> ist das Objekt, das an xray zur Introspektion übergeben wird.

Um mit einem bestimmten Objekt zu arbeiten erfordert häufig, dieses Objekt zu finden oder zu erzeugen, indem man mit <tt>StarDesktop</tt> oder <tt>thisComponent</tt> beginnt.

== Desktop, Dokumente, Selektionen ==
<tt>StarDesktop</tt> und <tt>ThisComponent</tt> sind OpenOffice.org-Basic-Befehle, die sich auf die Applikation bzw. das aktuell aktive Dokument beziehen.

Im Unterschied zu Microsoft Office ist OpenOffice.org eine Anwendung mit unterschiedlichen Komponenten. Beim Ausführen von Code möchte man häufig wissen, welche Komponente aktuell aktiv ist. Der obige Code zeigt eine Möglichkeit, dies zu überprüfen.

StarDesktop bezieht sich auf einen konzeptuellen Desktop (der historisch tatsächlich mal existiert hat) und meint de facto die Anwendung OpenOffice.org.

== Neue Dokumente erzeugen ==
Um ein neues Text-Dokument zu erzeugen:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/swriter", "_blank", 0, Array())
</code>
Um ein neues Tabellen-Dokument zu erzeugen:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/scalc", "_blank", 0, Array())
</code>
Ein sinnvoller Ansatz wäre, eine einfache Funktion zu schreiben:

<code>[oobas]
function fnNewDoc(sDocType as string)
fnNewDoc = StarDesktop.loadComponentFromURL("private:factory/" & sDocType , "_blank", 0, Array())
end function
</code>
Dann könnte man neue Dokumente ganz einfach erzeugen:

<code>[oobas]
oDoc = fnNewDoc("swriter")
oDoc = fnNewDoc("scalc")
oDoc = fnNewDoc("simpress")
oDoc = fnNewDoc("sdraw")
oDoc = fnNewDoc("smath")
</code>
Siehe http://api.openoffice.org/docs/common/ref/com/sun/star/frame/XComponentLoader.html .

== Ein bestehendes Dokument öffnen ==
Im folgenden Beispiel sehen Sie, wie Sie eine Datei öffnen können. OpenOffice.org URLs sind in [[DE: URL Grundlagen]] erläutert.

<code>[oobas]
sFile = "C:\Documents and Settings\danny\Desktop\MyCalc.sxc" ' Windows
sFile = "/home/danny/Desktop/MyCalc.sxc" ' Linux
sURL = ConvertToURL(sFile)
oDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
</code>
Auch hier könnte eine einfache Funktion das Schreiben verkürzen:

<code>[oobas]
function fnOpenDoc(sFile)
sURL = ConvertToURL(sFile)
fnOpenDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
end function
</code>
Beispiele für Aufrufe:

<code>[oobas]
oDoc = fnOpenDoc("C:\Documents and Settings\danny\Desktop\MyCalc.sxc") ' Windows
oDoc = fnOpenDoc("/home/danny/Desktop/MyCalc.sxc") ' Linux
</code>

== Die aktuelle Selektion ==
Häufig werden Sie eine Funktion schreiben wollen, die etwas mit dem aktuell selektierten Bereich anstellt. <tt>ThisComponent</tt> enthält die Methode <tt>getCurrentSelection</tt>. Da viele unterschiedliche Objekte selektiert sein könnten, werden Sie zuerst prüfen wollen, ob das selektierte Objekt über den Dienst verfügt, der die Methode enthält, mit der Sie das Objekt bearbeiten wollen.

Editieren Sie die Subroutine main im nachfolgenden Code und führen Sie sie mehrfach in einem Textdokument aus, wobei Sie unterschiedliche Objekte selektieren. (Um mehr als einen Textblock zu selektieren, betätigen Sie die '''Strg'''-Taste).

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
'xray.xray oCurSelection
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
msgbox "There are " & oCurSelection.getCount() & _
" selections in the current text document."
end if
end if
end sub
</code>
Wenn nichts selektiert ist, beträgt die Anzahl der Selektionen eins (nämlich der Einfügepunkt), wenn ein Textblock selektiert ist, beträgt die Anzahl ebenfalls eins, wenn zwei Textblöcke selektiert sind, beträgt sie drei: der Einfügepunkt sowie die beiden selektierten Textblöcke.

Übung 1: Modifizieren Sie den obigen Code so, dass er mit selektierten Zellbereichen in einem Tabellendokument funktioniert.

Frage 1: Wie hoch ist die Anzahl der Selektionen, wenn zwei Zellblöcke selektiert sind?

==Properties==
Wenn Sie die Zeile <tt>'xray.xray oCurSelection</tt> entkommentieren, so dass xray läuft, sehen Sie, dass das Objekt, worauf <tt>oCurSelection</tt> zeigt, eine "Property" namens <tt>Count</tt> besitzt, mit einer Beschreibung "pseudo-prop, read only". In OpenOffice.org Basic könnten Sie <tt>oCurSelection.count</tt> schreiben, da dies aber in keiner anderen Sprache, mit der Sie auf die OpenOffice.org API zugreifen können, möglich ist, werde ich versuchen, in diesem Wiki nur über Methoden zuzugreifen. (Möglicherweise vergesse ich das auch das eine oder andere Mal).

Das nächste Beispiel zeigt, wie man einen Property-Wert für die aktuellen Selektionen ändert.

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
nCount = oCurSelection.Count
'xray.xray oCurSelection.getByIndex(0)
'Warnung: Am Einfügepunkt wird die selbe Aktion zwei mal angewandt -
'das macht in diesem Fall nichts, kann aber durchaus problematisch werden.
for i = 0 to nCount - 1
oCurSelection.getByIndex(i).setPropertyValue("CharStyleName", "Strong Emphasis")
next
end if
end if
end sub
</code>

In OpenOffice.org Basic kann man die Zuweisung auch abkürzen:

<code>[oobas]
oCurSelection(i).CharStyleName = "Strong Emphasis"
</code>
Hier in diesem Wiki versuche ich, sowohl zur Indexierung als auch zur Zuweisung von Properties die vollständigen Methoden zu verwenden. Dadurch kann der Code leichter in andere Sprachen portiert werden und es hilft Ihnen auch, zu verstehen, was vor sich geht (nochmal: Bitte um Entschuldigung, wenn ich mal von dieser Regel abweiche, weil ich es eigentlich nicht gewohnt bin)

Übung 2: Schreiben Sie den obigen Code so um, dass die Warnung entfernt werden kann.

Siehe [[DE:Aktuelle Selektion]] ([[ Current selection]]).

=Iterativer Zugriff auf untergeordnete Objekte
(berechtigungsgesteuerte Auflistung)=
Manchmal ist zum Zugriff auf ein gewünschtes Objekt eine Enumeration (Auflistung) nötig. Beispielsweise ein Satz innerhalb eines Dokumentes oder innerhalb einer Auswahl.

Wenn innerhalb eines OpenOffice-Writer Dokuments eine Text selektiert wird, können die Methoden <tt>thisDocument.getText()</tt> und <tt>thisComponent.getCurrentSelection().getByIndex(i)</tt> verwand werden.
com.sun.star.text.TextRange ist die Schnittstelle (Interface): com.sun.star.container.XContentEnumerationAccess, it is possible to create an enumeration of the paragraphs for the current document or for a particular selection.

<code>[oobas]
' Create enumeration object
oTextElementEnum = thisComponent.getText().createEnumeration()
'or thisComponent.getCurrentSelection().getByIndex(i).createEnumeration()

' loop over all text elements
while oTextElementEnum.hasMoreElements()
oTextElement = oTextElementEnum.nextElement
if oTextElement.supportsService("com.sun.star.text.TextTable") then
MsgBox "The current block contains a table."
end if
if oTextElement.supportsService("com.sun.star.text.Paragraph") then
MsgBox "The current block contains a paragraph."
end if
wend
</code>
Aufgabe 3: Erweitere das obige Beispiel so, das eine MessageBox aller Worte des Schrifttyps "bold" zeigt .

=Named access=
Some objects provide named access to a particular type of subordinate object, some others indexed access, and some both named and indexed access.

For example if the current document in OpenOffice.org is a spreadsheet then to access a particular sheet can be done by index access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByIndex(0)
</code>
or named access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByName("Sheet1")
</code>
To check if an object with a particular name already exists use <tt>hasByName</tt>, for example:

<code>[oobas]
if thisComponent.getSheets.hasByName("Sheet1") then
</code>
To loop through all the available object names can be done like:

<code>[oobas]
mNames = thisComponent.getSheets.getElementnames
for i = lbound(mNames) to ubound(mNames)
msgbox mNames(i)
next
</code>

Some named subordinate objects also provide the interface: com.sun.star.container.XNameContainer. This interface defines that such objects should have the following methods: <tt>insertByName</tt>, <tt>replaceByname</tt> and <tt>removeByName</tt>.

E.g.

<code>[oobas]
thisComponent.getSheets.insertByName("NewSheet")
</code>

=Create new objects=
Some objects have services which implement interfaces to provide specific methods for creating a particular type of object.

For example if the current document is a Writer document then <tt>thisComponent.getText</tt> is an object that provides the service com.sun.star.text.Text which implements the interface com.sun.star.text.XSimpleText which defines the methods <tt>createTextCursor</tt> and <tt>createTextCursorByRange</tt>. Both of these methods create a text cursor for accessing the text of the document. These cursors are quite independent of the view cursor . The view cursor is visible on the screen and is manipulated by the user (and can be manipulated by program control), where as a text cursor is not visible on the screen and is solely used by program control. The following code snippet demonstrates creating a new text cursor, such that it starts at the same location as the viewCursor and is then moved independent of the view cursor.

<code>[oobas]
oVC = thisComponent.getCurrentController.getViewCursor
oCursor = oVC.getText.createTextCursorByRange(oVC)
oCursor.gotoStartOfSentence(false)
oCursor.gotoEndOfSentence(true)
msgbox oCursor.getString
</code>

Some objects are context dependent and get created using the method <tt>createInstance</tt> which is defined in the interface com.sun.star.lang.XMultiServiceFactory. For example to add a rectangle to the first page of a drawing document:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
dim aSize as new com.sun.star.awt.Size

aPoint.x = 1000
aPoint.y = 1000

aSize.Width = 10000
aSize.Height = 10000

oRectangleShape = thisComponent.createInstance("com.sun.star.drawing.RectangleShape")
oRectangleShape.Size = aSize
oRectangleShape.Position = aPoint

thisComponent.getDrawPages.getByIndex(0).add(oRectangleShape)
</code>

This example also uses UNO structs see below for more information on UNO stucts.

Some objects are context independent to create these objects use the OpenOffice.org Basic command createUnoService. For example to create the equivalent to StarDesktop:

<code>[oobas]
oDesktop = createUnoService("com.sun.star.frame.Desktop")
</code>

The process that I use to determine how to access or create an object is as follows:

Does the object already exist if so I should be able to access it from something like <tt>thisComponent</tt>.

Will the new object belong to another object, if so does the owner have a specific method for creating the object, if so use it.

The new object will belong to another object, but that object doesn't provide a specific method for creating it, but does provide <tt>createInstance</tt>. If the object doesn't provide <tt>createInstance</tt> are you sure you are using the correct object, or is it context independent.

I have found working out how to create an object to be quite difficult with existing documentation so I hope that this document/wiki will eventually make this clear.

==UNO structs==
UNO structures can be declared using the OpenOffice.org Basic command <tt>dim</tt>:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
</code>
Or by using the OpenOffice.org Basic command <tt>createUnoStruct</tt>:

<code>[oobas]
aPoint = createUnoStruct("com.sun.star.awt.Point")
</code>

{| border="1"
|'''Note:'''
|When declaring UNO structs case is important. Note that everything upto the name of the struct is lowercase, and that the name of the struct is in TitleCase.
|}

==Creating Listeners and Handlers==
Through the user interface it is possible to assign macros to some events:

OpenOffice.org versions 1.1.x: '''Tools > Configure… > Events'''.

OpenOffice.org versions 1.9.x and above: '''Tools > Customize… > Events'''.

It is also possible to assign macros to a wider range of events using the OpenOffice.org Basic command CreateUnoListener. This same command is used for creating both listeners and handlers. A listener checks for an event and always allows other listeners to respond to the event as well. A handler listens for an event, and can optionally consume the event so that other listeners don't get to act on it.

The following example creates a keyHandler:

<code>[oobas]
global IannzExampleKeyHandler

sub SetupKeyHandler
oController = thisComponent.currentController
IannzExampleKeyHandler = CreateUnoListener("KeyHandler_","com.sun.star.awt.XKeyHandler")
oController.addKeyHandler(IannzExampleKeyHandler) ' Register the listener
end sub

sub RemoveKeyHandler
thisComponent.currentController.removeKeyHandler(IannzExampleKeyHandler)
end sub

sub KeyHandler_disposing
end sub

function KeyHandler_keyReleased(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyReleased = False
end function

function KeyHandler_keyPressed(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyPressed = false 'Let other listeners handle the event
if oKeyEvent.modifiers = com.sun.star.awt.KeyModifier.MOD2 then 'Control key was pressed
if oKeyEvent.keyCode = com.sun.star.awt.Key.Q then
msgbox "Alt + Q was pressed"
KeyHandler_keyPressed = true 'Don't let other listeners process this event
end if
end if
end function
</code>
A variable declared as global keeps its value even after the macro exits. In this case we want to be able to use this variable later to remove the handler. As variables declared globally could be used in other libraries to try and avoid conflict I start all my global variables with Iannz my registered name for the OpenOffice.org web site.

<tt>sub SetupKeyHandler</tt> sets up the handler. The first parameter to CreateUnoListener is the staring name for the methods that will be called when that type of event occurs in this example .<tt>"KeyHandler_"</tt>.

The second parameter is the name of the interface for the listener or handler, "com.sun.star.awt.XKeyHandler". The name is case sensitive, everything up to and including the module name is always lowercase, the name of the interface always starts with "X" and the remainder is in TitleCase.

Use the SDK to find out what methods the interface must supply. You must supply routines for all of these methods even if you don't intend to use them. You also need to supply a disposing method. The names of these routines start with the string given in the first parameter to CreateUnoListener , in this example <tt>"KeyHandler_"</tt>.

Thus in the example there is <tt>KeyHandler_disposing</tt> and <tt>KeyHandler_keyReleased</tt> which don't actually do anything but are required, and <tt>KeyHandler_keyPressed</tt> which actually does the job.

<tt>sub RemoveKeyHandler</tt> demonstrates how to remove the handler.

=OpenOffice.org constants=
The above example uses OpenOffice.org constants.

E.g. com.sun.star.awt.KeyModifier.MOD2

OpenOffice.org constants are case sensitive. Everything up to and including the module name is always lowercase. The constant group is in TitleCase. The actual constant name is always UPPERCASE.

Programmers not using OpenOffice.org Basic may not have access to these constants.

=Using the recorder=
See [[ The OpenOffice.org recorder and UNO dispatch calls]] section for a discussion on recording UNO Dispatch commands versus writing API calls.

[[Category:Basic:Tutorials]]

DE/Makro Basic Tutorial

2006-09-06T01:30:51Z

Global667: /* Iterative Access to Subordinate Objects (Enumeration access) */

[[Category:de.openoffice.org|Makro Basic Tutorial]]

{| cellspacing=0 cellpadding=5 style="border: 1px solid black;"
| bgcolor=orange colspan=2 |'''Achtung, work in progress'''
Dieses Dokument wird gerade übersetzt, wer mag, darf auch gerne helfen.
|-
|'''Arbeitstitel:''' || "Einführung: Basic für OOo-Erweiterungen"
|-
|'''Originaldokument:''' || [[Extensions_development_basic]] 
|-
|'''Ursprünglicher Autor:''' || Ian Laurenson
|-
| offene Fragen: || sind mit ??? gekennzeichnet
|}

Diese Seite soll Ihnen eine Einführung in das Schreiben von Makros mit OpenOffice.org Basic geben. Grundkenntnisse im Programmieren werden vorausgesetzt. Bitte fühlen Sie sich frei, diese Seite zu editieren, um sie lesbarer zu machen. Ich hoffe, das Sie Ihnen von Nutzen sein wird.

Wenn Sie bereits mit den Grundlagen vertraut sind, können Sie sich auch direkt im KochBuch ([[CookBook]]) Wrapper (Hüllfunktionen ???) und Beispiele anschauen.

= Wohin schreibe ich den Code? =

Der Basic-Code wird bei OpenOffice.org in '''Modulen''' gespeichert, die in '''Bibliotheken''' zusammengefasst sind.

Eine Bibliothek kann
* '''allgemein''', also für die gesamte (Netzwerk-) Installation verfügbar sein ("OOo Makros und Dialoge")
* nur für den aktuellen '''Benutzer''' verfügbar sein ("Meine Makros und Dialoge")
* in einem '''Dokument''' oder in einer Vorlage abgelegt sein, so dass ihr Code nur zur Verfügung steht, wenn das Dokument geöffnet ist.
Bibliotheken, die nicht in einem Dokument abgelegt sind (also allgemein oder für den aktuellen Benutzer verfügbare Bibliotheken) werden im Folgenden als ''OpenOffice.org Bibliotheken'' zusammengefasst.

Der physische Speicherort für diese OpenOffice.org Bibliotheken wird unter '''Extras > Optionen… > OpenOffice.org > Pfade > BASIC''' festgelegt.

{| border="1"
|'''Anmerkung:'''
|Hüten Sie sich, Bibliotheken auf Dateisystem-Ebene zu verschieben oder zu kopieren. Benutzen Sie stattdessen den Dialog "Makros verwalten" oder den Paket-Manager
|}

Module in Bibliotheken können maximal 64kb groß sein. Eine Bibliothek kann bis zu 16 000 Module enthalten. Weitere Infos finden Sie in der Online-Hilfe unter "Module und Bibliotheken" (???).

= Die Entwicklungsumgebung (IDE) =

Öffnen Sie die Entwicklungsumgebung:
* in OOo 1.1.x unter '''Extras > Makros > Makro ...'''
* in OOo 1.9.x und höher unter ''' Extras > Makros > Makros verwalten > OpenOffice.org Basic...'''

Zum Einstieg benutzen wir das "Modul1" aus der Bibliothek "Standard" des aktuellen Benutzers:

Geben Sie einen Namen für das neue Makro ein: "HelloWorld"

Wählen Sie die Option '''Standard''' im Auswahlfeld "Makro aus:"

Klicken Sie auf '''Neu'''

Jetzt sollten Sie etwa folgendes sehen:

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub

Sub HelloWorld

End Sub
</code>

Der Cursor sollte am Anfang der Zeile <tt>Sub HelloWorld</tt> stehen.

{| border="1"
|'''Achtung:'''
|Das geöffnete IDE-Fenster ist sowohl über das Menü im OpenOffice.org-Fenster als auch über die Programmleiste des Betriebssystems erreichbar.
|}

= Eingeben von Programm-Code =

Löschen Sie folgende Zeilen:

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub
</code>

Schreiben Sie unterhalb der Zeile "Sub HelloWorld": <tt>msgbox "Hello World!"</tt>, so dass es in etwa so aussieht:

<code>[oobas]
Sub HelloWorld
msgbox "Hello World!"
End Sub
</code>

{| border="1"
|'''Achtung:'''
|Die IDE beherrscht zwar keine "code completion"(->dt.Auto-Vervollständigung), also die Fähigkeit eines Editors den Text automatisch zu vervollständigen, um den Schreibprozess zu beschleunigen, während der Eingabe, verfügt aber über eine kontext-sensitive Hilfe, wenn Sie während der Eingabe F1 oder "Hilfe" drücken oder der Cursor in einem Befehl steht. Bei OpenOffice.org Basic-Befehlen wird die Groß- und Kleinschreibung nicht unterschieden. So sind die Eingaben msgbox, MSGBOX oder Msgbox äquivalent. Strings (Textvariablen) werden in doppelte Anführrungszeichen eingeschlossen.
|-
|}

= Den Code ausführen =

Hierfür gibt es mehrere Möglichkeiten:

* direkt aus der IDE: das Symbol '''Ausführen''' (das 3. Symbol in der 2. Leiste) ruft das ERSTE Makro des aktuellen Moduls auf.
* aus dem Menü "Extras":
** (Version 1.1.x) '''Extras > Makros > Makro…''';
** (Version 1.9.x und höher) '''Extras > Makro > Makro auführen…'''
* Dem Makro ein Tastaturkürzel zuweisen (todo).
* Dem Makro einen Menüeintrag zuweisen (todo).
* Dem Makro ein Symbolleisten-Symbol zuweisen (todo).
* Ein Kontroll-Element in einem Dokument erstellen (todo).
* Das Makro einem Ereignis zuweisen (todo)

Führen Sie für den Anfang die "HelloWorld"-Subroutine aus, indem Sie auf das '''Ausführen'''-Symbol klicken. Ein kleiner Dialog mit dem Titel "soffice" und dem Text "Hello World" sollte aufpoppen.

= Speichern des Code =

Der Code wird immer automatisch gespeichert, wenn sein Container gespeichert wird. Wenn das Modul also in einer (allgemeinen oder benutzerspezifischen) OpenOffice.org-Bibliothek enthalten ist, wird es beim Schließen der Anwendung OpenOffice.org gespeichert. Entsprechend werden Dokument-interne Bibliotheken biem Speichern des Dokuments mit-gesichert.

Auf der Standard-Symbolleiste der IDE (normalerweise die oberste Symbolleiste) finden Sie ein Symbol "Speichern". Befindet sich der Code in einem Dokument oder einer Vorlage, dann speichert der Klick auf dieses Symbol das gesamte Dokument. Handelt es sich dagegen um eine OpenOffice.org-Bibliothek, wird nur die aktuelle Bibliothek gespeichert.

= Variablen =

Bei Variablen kann durch <tt>Option Explicit</tt> zu Beginn des Moduls die explizite Deklaration erzwungen werden. Zu Sinn und Unsinn des Deklarierens von Variablen lesen Sie [http://www.oooforum.org/forum/viewtopic.phtml?t=5845 diese Diskussion].

In dieser Diskussion vertritt der ursprüngliche Autor dieses Wiki-Beitrags die Position, dass Variablen immer deklariert werden sollten. Mittlerweile hat er seine Meinung geändert. Kurz: es ist eine Frage des persönlichen Geschmacks. Unabhängig davon sollten nach Auffassung des ursprünglichen Autors Variablen nach folgener Konvention benannt werden, die auch bei den Beispielen aus diesem Wiki verwendet wurde:

Der erste Buchstabe der Variable steht für den Typ des in der Variable gespeicherten Wertes. Dabei bezeichnen folgende Buchstaben die entsprechenden Datentypen (in Anlehung an das Tutorial.pdf von Sun):

{| border="1"
|'''''Buchstabe'''''
|'''''Bedeutung'''''
|-
|a
|Struktur (Structure)
|-
|b
|Bool'sch (WAHR oder FALSCH)
|-
|e
|Aufzählung (Enumeration). Diese Variable kann nur einen begrenzten Satz von Werten enthalten.
|-
|f
|Fließkomma-Zahl (3.402823 x 1038 bis 1.401298 x 10-45. Eine einzelne Variable kann bis zu 4 Bytes umfassen) "Double" (doppelte Genauigkeit, 1.79769313486232 x 10308 bis 4.94065645841247 x 10-324. Eine Double-Variable kann bis zu 8 Bytes umfassen) Währung (-922337203685477.5808 bis +922337203685477.5807 ebenfalls 8 Byte umfassend)
|-
|m
|Feld (Array) (aka Sequenz aka Matrix)
|-
|n
|Integer (-32768 to 32767.) oder Long (-2147483648 and 2147483647).
|-
|o
|Objekt, Service oder Interface
|-
|s
|Text (String) (Eine String-Variable kann bis zu 65535 Unicode-Zeichen enthalten).
|-
|x
|Schnittstelle (Interface), um anzuzeigen, dass nur Methoden einer bstimmten Schnittstelle eines Objekts verwendet werden.
|-
|v
|Variant, irgend ein Typ
|-
|}

Benutzen Sie lange, beschreibende Variablennamen unter Verwendung von CamelCase (Groß-Klein-Schreibung).

{| border="1"
|'''Achtung:'''
|Bei benutzerdefinierten OpenOffice.org Basic-Variablen spielt die Groß-/Kleinschreibunge keine Rolle. Bei UNO-API-Konstanten aber sehr wohl!
|}

Ausnahmen von der Regel, lange Namen zu verwenden, sind Index-Variablen (meist i, j oder k), sowie Strings (meist als s bezeichnet).

Bearbeiten Sie nun die sub HelloWorld, so dass der Code ungefähr wie im folgenden aussieht und führen Sie sie aus:

<code>[oobas]
sub HelloWorld
dim i as integer 'This line is optional
for i = 0 to 2
'These lines are indented for ease of reading only
'all your code should be like this for lonog time survival
msgbox "Hello World " & i
next i
end sub
</code>

Mehr Infos zur Verwendung von Variablen erhalten Sie in der Online-Hilfe unter "Variablen benutzen" (???)

= Die OpenOffice.org API =

Dieser Abschnitt beginnt mit einem Beispiel. Anschließend wird das Beispiel erläutert.

Versuchen Sie den folgenden Code in Dokumenten unterschiedlichen Typs auszuführen:

<code>[oobas]
sub main
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
msgbox fnWhichComponent(thisComponent)
end sub

function fnWhichComponent(oDoc) as string
if HasUnoInterfaces(oDoc, "com.sun.star.lang.XServiceInfo") then
if thisComponent.supportsService ("com.sun.star.text.GenericTextDocument") then
fnWhichComponent = "Text"
elseif thisComponent.supportsService("com.sun.star.sheet.SpreadsheetDocument") then
fnWhichComponent = "Spreadsheet"
elseif thisComponent.supportsService("com.sun.star.presentation.PresentationDocument") then
fnWhichComponent = "Presentation"
elseif thisComponent.supportsService("com.sun.star.drawing.GenericDrawingDocument") then
fnWhichComponent = "Drawing"
else
fnWhichComponent = "Oops current document something else"
end if
else
fnWhichComponent = "Not a document"
end if
End function
</code>

== Namenskonventionen für Subroutinen ==
im obigen Beispiel beginnt die Benutzer-definierte Funktion mit den Buchstaben "fn". Diese Konvention (an die sich der ursprüngliche Autor hält) kennzeichnet eine Funktion als Benutzer-definiert. Entsprechend beginnt eine Benutzer-definierte Subroutine mit "sub". Diese im Folgenden benutzten Konventionen sollen Ihnen als Anfängern helfen, Benutzer-definierte von eingebauten Routinen/Funktionen zu unterscheiden.

== Einführung in die OpenOffice.org API ==

In diesem Abschnitt werden folgende Begriffe erläutert:

* Interface (Schnittstelle)
* Modul
* Service (Dienst)
* Methode
* Property (Eigenschaft)

Den Unterschied zwischen einer Schnittstelle und einem Service zu kennen, ist zwar nicht unbedingt Voraussetzung zum Programmieren unter OpenOffice.org, aber es hilft, die Dokumentation zu verstehen, und auch bei der Introspektion. Möglicherweise werden Sie den folgenden Abschnitt mindestens zwei mal lesen müssen!

Eine Schnittstelle ist eine ''Definition'' eines Satzes von Methoden (und ihren Argumenten), die ein Dienst, der diese Schnittstelle implementiert, enthalten muss.

Schnittstellen werden aus Gründen der Namensgebung zu '''Modulen''' gruppiert. Alle Schnittstellen (und Dienste) beginnen mit <tt>com.sun.star</tt>, gefolgt vom Modul-Namen, dann kommt der Name der Schnittstelle (oder des Dienstes).

Beispielsweise bieten die meisten Dienste die Schnittstelle <tt>com.sun.star.beans.XPropertySet</tt>. Diese Schnittstelle ist im Modul <tt>beans</tt> gespeichert und ermöglicht Zugriff auf die Eigenschaften (Properties) eines Dienstes. Eine '''Eigenschaft''' ist ein Wert, eine '''Methode''' ist dagegen eine Aktion.

Ein OpenOffice.org-Objekt kann viele Dienste enthalten.

Ein OpenOffice.org-Objekt kann einen Dienst enthalten, der eine Schnittstelle implementiert, in welcher eine Methode beschreibt, dass ein anderes OpenOffice.org-Objekt zurückgegeben wird.

== Introspektion ==

'''HasUnoInterfaces''' ist eine OpenOffice.org-Basic-Funktion zur Introspektion. Informieren Sie sich über [http://www.oooforum.org/forum/viewtopic.phtml?t=7068 Introspektion in anderen Sprachen].

<tt>HasUnoInterfaces</tt> gibt <code>true</code> zurück, wenn beim spezifizierten Objekt alle spezifizierten Schnittstellen verfügbar sind.

Die meisten OpenOffice.org-Objekte enthalten die Methode '''supportsService''' weil sie die Schnittstelle <code>com.sun.star.lang.XServiceInfo</code> enthalten.

Im obigen Beispiel prüft <tt>HasUnoInterfaces</tt>, ob das aktuelle Dokument die Schnittstelle <tt>com.sun.star.lang.XServiceInfo</tt> implementiert, da andernfalls die Methode <tt>supportsService</tt> fehlen würde. Der Aufruf dieser Methode würde in diesem Fall einen Laufzeitfehler verursachen.

<tt>supportsService</tt> ist eine Methode, die den Wert <code>true</code> zurückgibt, wenn der spezifizierte Service verfügbar ist. Das obige Beispiel prüft das Vorhandensein eines Service, um so den Typ des aktuell aktiven Dokuments zu bestimmen.

== X-Ray tool ==
Die Benutzung von <tt>HasUnoInterfaces</tt> und <tt>supportsService</tt> reicht aus, um sich zur Laufzeit über ein Objekt zu informieren, aber zum Lernen eignet sich das [http://ooomacros.org/dev.php#101416 X-Ray tool von Bernard Marcelly] viel besser. Laden Sie das ZIP-File herunter, entpacken Sie es und öffnen Sie das enthaltene Dokument mit OpenOffice.org. Befolgen Sie anschließend die Installationsanweisungen.

Das '''X-Ray tool''' verlangt bei der Konfiguration eine lokale Kopie des OpenOffice.org SDK. Laden Sie es von [http://www.openoffice.org/dev_docs/source/sdk/ hier] herunter und entpacken Sie es.

Nun können Sie die beiden auskommentierten Zeilen des obigen Beispiels entkommentieren (den Apostroph entfernen):

<code>[oobas]
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
</code>

Führen Sie das Makro dann erneut aus.

Ab Xray Version 5 heißt das Kommando einfach '''xray'''.

'''BasicLibraries''' ist ein OpenOffice.org-Basic-Befehl, der ein Objekt zurückgibt, mit dem man auf die OpenOffice.org Bibliotheken zugreifen kann. Die Methode <tt>loadLibrary</tt> macht die Routinen aus dieser Bibliothek verfügbar.

<tt>xray.xray</tt> spezifiziert die Subroutine <tt>xray</tt> im Modul <tt>xray</tt> in dieser Bibliothek, <tt>thisComponent</tt> ist das Objekt, das an xray zur Introspektion übergeben wird.

Um mit einem bestimmten Objekt zu arbeiten erfordert häufig, dieses Objekt zu finden oder zu erzeugen, indem man mit <tt>StarDesktop</tt> oder <tt>thisComponent</tt> beginnt.

== Desktop, Dokumente, Selektionen ==
<tt>StarDesktop</tt> und <tt>ThisComponent</tt> sind OpenOffice.org-Basic-Befehle, die sich auf die Applikation bzw. das aktuell aktive Dokument beziehen.

Im Unterschied zu Microsoft Office ist OpenOffice.org eine Anwendung mit unterschiedlichen Komponenten. Beim Ausführen von Code möchte man häufig wissen, welche Komponente aktuell aktiv ist. Der obige Code zeigt eine Möglichkeit, dies zu überprüfen.

StarDesktop bezieht sich auf einen konzeptuellen Desktop (der historisch tatsächlich mal existiert hat) und meint de facto die Anwendung OpenOffice.org.

== Neue Dokumente erzeugen ==
Um ein neues Text-Dokument zu erzeugen:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/swriter", "_blank", 0, Array())
</code>
Um ein neues Tabellen-Dokument zu erzeugen:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/scalc", "_blank", 0, Array())
</code>
Ein sinnvoller Ansatz wäre, eine einfache Funktion zu schreiben:

<code>[oobas]
function fnNewDoc(sDocType as string)
fnNewDoc = StarDesktop.loadComponentFromURL("private:factory/" & sDocType , "_blank", 0, Array())
end function
</code>
Dann könnte man neue Dokumente ganz einfach erzeugen:

<code>[oobas]
oDoc = fnNewDoc("swriter")
oDoc = fnNewDoc("scalc")
oDoc = fnNewDoc("simpress")
oDoc = fnNewDoc("sdraw")
oDoc = fnNewDoc("smath")
</code>
Siehe http://api.openoffice.org/docs/common/ref/com/sun/star/frame/XComponentLoader.html .

== Ein bestehendes Dokument öffnen ==
Im folgenden Beispiel sehen Sie, wie Sie eine Datei öffnen können. OpenOffice.org URLs sind in [[DE: URL Grundlagen]] erläutert.

<code>[oobas]
sFile = "C:\Documents and Settings\danny\Desktop\MyCalc.sxc" ' Windows
sFile = "/home/danny/Desktop/MyCalc.sxc" ' Linux
sURL = ConvertToURL(sFile)
oDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
</code>
Auch hier könnte eine einfache Funktion das Schreiben verkürzen:

<code>[oobas]
function fnOpenDoc(sFile)
sURL = ConvertToURL(sFile)
fnOpenDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
end function
</code>
Beispiele für Aufrufe:

<code>[oobas]
oDoc = fnOpenDoc("C:\Documents and Settings\danny\Desktop\MyCalc.sxc") ' Windows
oDoc = fnOpenDoc("/home/danny/Desktop/MyCalc.sxc") ' Linux
</code>

== Die aktuelle Selektion ==
Häufig werden Sie eine Funktion schreiben wollen, die etwas mit dem aktuell selektierten Bereich anstellt. <tt>ThisComponent</tt> enthält die Methode <tt>getCurrentSelection</tt>. Da viele unterschiedliche Objekte selektiert sein könnten, werden Sie zuerst prüfen wollen, ob das selektierte Objekt über den Dienst verfügt, der die Methode enthält, mit der Sie das Objekt bearbeiten wollen.

Editieren Sie die Subroutine main im nachfolgenden Code und führen Sie sie mehrfach in einem Textdokument aus, wobei Sie unterschiedliche Objekte selektieren. (Um mehr als einen Textblock zu selektieren, betätigen Sie die '''Strg'''-Taste).

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
'xray.xray oCurSelection
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
msgbox "There are " & oCurSelection.getCount() & _
" selections in the current text document."
end if
end if
end sub
</code>
Wenn nichts selektiert ist, beträgt die Anzahl der Selektionen eins (nämlich der Einfügepunkt), wenn ein Textblock selektiert ist, beträgt die Anzahl ebenfalls eins, wenn zwei Textblöcke selektiert sind, beträgt sie drei: der Einfügepunkt sowie die beiden selektierten Textblöcke.

Übung 1: Modifizieren Sie den obigen Code so, dass er mit selektierten Zellbereichen in einem Tabellendokument funktioniert.

Frage 1: Wie hoch ist die Anzahl der Selektionen, wenn zwei Zellblöcke selektiert sind?

==Properties==
Wenn Sie die Zeile <tt>'xray.xray oCurSelection</tt> entkommentieren, so dass xray läuft, sehen Sie, dass das Objekt, worauf <tt>oCurSelection</tt> zeigt, eine "Property" namens <tt>Count</tt> besitzt, mit einer Beschreibung "pseudo-prop, read only". In OpenOffice.org Basic könnten Sie <tt>oCurSelection.count</tt> schreiben, da dies aber in keiner anderen Sprache, mit der Sie auf die OpenOffice.org API zugreifen können, möglich ist, werde ich versuchen, in diesem Wiki nur über Methoden zuzugreifen. (Möglicherweise vergesse ich das auch das eine oder andere Mal).

Das nächste Beispiel zeigt, wie man einen Property-Wert für die aktuellen Selektionen ändert.

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
nCount = oCurSelection.Count
'xray.xray oCurSelection.getByIndex(0)
'Warnung: Am Einfügepunkt wird die selbe Aktion zwei mal angewandt -
'das macht in diesem Fall nichts, kann aber durchaus problematisch werden.
for i = 0 to nCount - 1
oCurSelection.getByIndex(i).setPropertyValue("CharStyleName", "Strong Emphasis")
next
end if
end if
end sub
</code>

In OpenOffice.org Basic kann man die Zuweisung auch abkürzen:

<code>[oobas]
oCurSelection(i).CharStyleName = "Strong Emphasis"
</code>
Hier in diesem Wiki versuche ich, sowohl zur Indexierung als auch zur Zuweisung von Properties die vollständigen Methoden zu verwenden. Dadurch kann der Code leichter in andere Sprachen portiert werden und es hilft Ihnen auch, zu verstehen, was vor sich geht (nochmal: Bitte um Entschuldigung, wenn ich mal von dieser Regel abweiche, weil ich es eigentlich nicht gewohnt bin)

Übung 2: Schreiben Sie den obigen Code so um, dass die Warnung entfernt werden kann.

Siehe [[DE:Aktuelle Selektion]] ([[ Current selection]]).

=Iterativer Zugriff auf untergeordnete Objekte (berechtigungsgesteuerte Auflistung)=
Manchmal ist zum Zugriff auf ein gewünschtes Objekt eine Enumeration (Auflistung) nötig. Beispielsweise ein Satz innerhalb eines Dokumentes oder innerhalb einer Auswahl.

Wenn innerhalb eines OpenOffice-Writer Dokuments eine Text selektiert wird, können die Methoden <tt>thisDocument.getText()</tt> und <tt>thisComponent.getCurrentSelection().getByIndex(i)</tt> verwand werden.
com.sun.star.text.TextRange ist die Schnittstelle (Interface): com.sun.star.container.XContentEnumerationAccess, it is possible to create an enumeration of the paragraphs for the current document or for a particular selection.

<code>[oobas]
' Create enumeration object
oTextElementEnum = thisComponent.getText().createEnumeration()
'or thisComponent.getCurrentSelection().getByIndex(i).createEnumeration()

' loop over all text elements
while oTextElementEnum.hasMoreElements()
oTextElement = oTextElementEnum.nextElement
if oTextElement.supportsService("com.sun.star.text.TextTable") then
MsgBox "The current block contains a table."
end if
if oTextElement.supportsService("com.sun.star.text.Paragraph") then
MsgBox "The current block contains a paragraph."
end if
wend
</code>
Aufgabe 3: Erweitere das obige Beispiel so, das eine MessageBox aller Worte des Schrifttyps "bold" zeigt .

=Named access=
Some objects provide named access to a particular type of subordinate object, some others indexed access, and some both named and indexed access.

For example if the current document in OpenOffice.org is a spreadsheet then to access a particular sheet can be done by index access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByIndex(0)
</code>
or named access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByName("Sheet1")
</code>
To check if an object with a particular name already exists use <tt>hasByName</tt>, for example:

<code>[oobas]
if thisComponent.getSheets.hasByName("Sheet1") then
</code>
To loop through all the available object names can be done like:

<code>[oobas]
mNames = thisComponent.getSheets.getElementnames
for i = lbound(mNames) to ubound(mNames)
msgbox mNames(i)
next
</code>

Some named subordinate objects also provide the interface: com.sun.star.container.XNameContainer. This interface defines that such objects should have the following methods: <tt>insertByName</tt>, <tt>replaceByname</tt> and <tt>removeByName</tt>.

E.g.

<code>[oobas]
thisComponent.getSheets.insertByName("NewSheet")
</code>

=Create new objects=
Some objects have services which implement interfaces to provide specific methods for creating a particular type of object.

For example if the current document is a Writer document then <tt>thisComponent.getText</tt> is an object that provides the service com.sun.star.text.Text which implements the interface com.sun.star.text.XSimpleText which defines the methods <tt>createTextCursor</tt> and <tt>createTextCursorByRange</tt>. Both of these methods create a text cursor for accessing the text of the document. These cursors are quite independent of the view cursor . The view cursor is visible on the screen and is manipulated by the user (and can be manipulated by program control), where as a text cursor is not visible on the screen and is solely used by program control. The following code snippet demonstrates creating a new text cursor, such that it starts at the same location as the viewCursor and is then moved independent of the view cursor.

<code>[oobas]
oVC = thisComponent.getCurrentController.getViewCursor
oCursor = oVC.getText.createTextCursorByRange(oVC)
oCursor.gotoStartOfSentence(false)
oCursor.gotoEndOfSentence(true)
msgbox oCursor.getString
</code>

Some objects are context dependent and get created using the method <tt>createInstance</tt> which is defined in the interface com.sun.star.lang.XMultiServiceFactory. For example to add a rectangle to the first page of a drawing document:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
dim aSize as new com.sun.star.awt.Size

aPoint.x = 1000
aPoint.y = 1000

aSize.Width = 10000
aSize.Height = 10000

oRectangleShape = thisComponent.createInstance("com.sun.star.drawing.RectangleShape")
oRectangleShape.Size = aSize
oRectangleShape.Position = aPoint

thisComponent.getDrawPages.getByIndex(0).add(oRectangleShape)
</code>

This example also uses UNO structs see below for more information on UNO stucts.

Some objects are context independent to create these objects use the OpenOffice.org Basic command createUnoService. For example to create the equivalent to StarDesktop:

<code>[oobas]
oDesktop = createUnoService("com.sun.star.frame.Desktop")
</code>

The process that I use to determine how to access or create an object is as follows:

Does the object already exist if so I should be able to access it from something like <tt>thisComponent</tt>.

Will the new object belong to another object, if so does the owner have a specific method for creating the object, if so use it.

The new object will belong to another object, but that object doesn't provide a specific method for creating it, but does provide <tt>createInstance</tt>. If the object doesn't provide <tt>createInstance</tt> are you sure you are using the correct object, or is it context independent.

I have found working out how to create an object to be quite difficult with existing documentation so I hope that this document/wiki will eventually make this clear.

==UNO structs==
UNO structures can be declared using the OpenOffice.org Basic command <tt>dim</tt>:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
</code>
Or by using the OpenOffice.org Basic command <tt>createUnoStruct</tt>:

<code>[oobas]
aPoint = createUnoStruct("com.sun.star.awt.Point")
</code>

{| border="1"
|'''Note:'''
|When declaring UNO structs case is important. Note that everything upto the name of the struct is lowercase, and that the name of the struct is in TitleCase.
|}

==Creating Listeners and Handlers==
Through the user interface it is possible to assign macros to some events:

OpenOffice.org versions 1.1.x: '''Tools > Configure… > Events'''.

OpenOffice.org versions 1.9.x and above: '''Tools > Customize… > Events'''.

It is also possible to assign macros to a wider range of events using the OpenOffice.org Basic command CreateUnoListener. This same command is used for creating both listeners and handlers. A listener checks for an event and always allows other listeners to respond to the event as well. A handler listens for an event, and can optionally consume the event so that other listeners don't get to act on it.

The following example creates a keyHandler:

<code>[oobas]
global IannzExampleKeyHandler

sub SetupKeyHandler
oController = thisComponent.currentController
IannzExampleKeyHandler = CreateUnoListener("KeyHandler_","com.sun.star.awt.XKeyHandler")
oController.addKeyHandler(IannzExampleKeyHandler) ' Register the listener
end sub

sub RemoveKeyHandler
thisComponent.currentController.removeKeyHandler(IannzExampleKeyHandler)
end sub

sub KeyHandler_disposing
end sub

function KeyHandler_keyReleased(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyReleased = False
end function

function KeyHandler_keyPressed(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyPressed = false 'Let other listeners handle the event
if oKeyEvent.modifiers = com.sun.star.awt.KeyModifier.MOD2 then 'Control key was pressed
if oKeyEvent.keyCode = com.sun.star.awt.Key.Q then
msgbox "Alt + Q was pressed"
KeyHandler_keyPressed = true 'Don't let other listeners process this event
end if
end if
end function
</code>
A variable declared as global keeps its value even after the macro exits. In this case we want to be able to use this variable later to remove the handler. As variables declared globally could be used in other libraries to try and avoid conflict I start all my global variables with Iannz my registered name for the OpenOffice.org web site.

<tt>sub SetupKeyHandler</tt> sets up the handler. The first parameter to CreateUnoListener is the staring name for the methods that will be called when that type of event occurs in this example .<tt>"KeyHandler_"</tt>.

The second parameter is the name of the interface for the listener or handler, "com.sun.star.awt.XKeyHandler". The name is case sensitive, everything up to and including the module name is always lowercase, the name of the interface always starts with "X" and the remainder is in TitleCase.

Use the SDK to find out what methods the interface must supply. You must supply routines for all of these methods even if you don't intend to use them. You also need to supply a disposing method. The names of these routines start with the string given in the first parameter to CreateUnoListener , in this example <tt>"KeyHandler_"</tt>.

Thus in the example there is <tt>KeyHandler_disposing</tt> and <tt>KeyHandler_keyReleased</tt> which don't actually do anything but are required, and <tt>KeyHandler_keyPressed</tt> which actually does the job.

<tt>sub RemoveKeyHandler</tt> demonstrates how to remove the handler.

=OpenOffice.org constants=
The above example uses OpenOffice.org constants.

E.g. com.sun.star.awt.KeyModifier.MOD2

OpenOffice.org constants are case sensitive. Everything up to and including the module name is always lowercase. The constant group is in TitleCase. The actual constant name is always UPPERCASE.

Programmers not using OpenOffice.org Basic may not have access to these constants.

=Using the recorder=
See [[ The OpenOffice.org recorder and UNO dispatch calls]] section for a discussion on recording UNO Dispatch commands versus writing API calls.

[[Category:Basic:Tutorials]]

DE/Makro Basic Tutorial

2006-09-06T01:08:48Z

Global667: /* X-Ray tool */

[[Category:de.openoffice.org|Makro Basic Tutorial]]

{| cellspacing=0 cellpadding=5 style="border: 1px solid black;"
| bgcolor=orange colspan=2 |'''Achtung, work in progress'''
Dieses Dokument wird gerade übersetzt, wer mag, darf auch gerne helfen.
|-
|'''Arbeitstitel:''' || "Einführung: Basic für OOo-Erweiterungen"
|-
|'''Originaldokument:''' || [[Extensions_development_basic]] 
|-
|'''Ursprünglicher Autor:''' || Ian Laurenson
|-
| offene Fragen: || sind mit ??? gekennzeichnet
|}

Diese Seite soll Ihnen eine Einführung in das Schreiben von Makros mit OpenOffice.org Basic geben. Grundkenntnisse im Programmieren werden vorausgesetzt. Bitte fühlen Sie sich frei, diese Seite zu editieren, um sie lesbarer zu machen. Ich hoffe, das Sie Ihnen von Nutzen sein wird.

Wenn Sie bereits mit den Grundlagen vertraut sind, können Sie sich auch direkt im KochBuch ([[CookBook]]) Wrapper (Hüllfunktionen ???) und Beispiele anschauen.

= Wohin schreibe ich den Code? =

Der Basic-Code wird bei OpenOffice.org in '''Modulen''' gespeichert, die in '''Bibliotheken''' zusammengefasst sind.

Eine Bibliothek kann
* '''allgemein''', also für die gesamte (Netzwerk-) Installation verfügbar sein ("OOo Makros und Dialoge")
* nur für den aktuellen '''Benutzer''' verfügbar sein ("Meine Makros und Dialoge")
* in einem '''Dokument''' oder in einer Vorlage abgelegt sein, so dass ihr Code nur zur Verfügung steht, wenn das Dokument geöffnet ist.
Bibliotheken, die nicht in einem Dokument abgelegt sind (also allgemein oder für den aktuellen Benutzer verfügbare Bibliotheken) werden im Folgenden als ''OpenOffice.org Bibliotheken'' zusammengefasst.

Der physische Speicherort für diese OpenOffice.org Bibliotheken wird unter '''Extras > Optionen… > OpenOffice.org > Pfade > BASIC''' festgelegt.

{| border="1"
|'''Anmerkung:'''
|Hüten Sie sich, Bibliotheken auf Dateisystem-Ebene zu verschieben oder zu kopieren. Benutzen Sie stattdessen den Dialog "Makros verwalten" oder den Paket-Manager
|}

Module in Bibliotheken können maximal 64kb groß sein. Eine Bibliothek kann bis zu 16 000 Module enthalten. Weitere Infos finden Sie in der Online-Hilfe unter "Module und Bibliotheken" (???).

= Die Entwicklungsumgebung (IDE) =

Öffnen Sie die Entwicklungsumgebung:
* in OOo 1.1.x unter '''Extras > Makros > Makro ...'''
* in OOo 1.9.x und höher unter ''' Extras > Makros > Makros verwalten > OpenOffice.org Basic...'''

Zum Einstieg benutzen wir das "Modul1" aus der Bibliothek "Standard" des aktuellen Benutzers:

Geben Sie einen Namen für das neue Makro ein: "HelloWorld"

Wählen Sie die Option '''Standard''' im Auswahlfeld "Makro aus:"

Klicken Sie auf '''Neu'''

Jetzt sollten Sie etwa folgendes sehen:

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub

Sub HelloWorld

End Sub
</code>

Der Cursor sollte am Anfang der Zeile <tt>Sub HelloWorld</tt> stehen.

{| border="1"
|'''Achtung:'''
|Das geöffnete IDE-Fenster ist sowohl über das Menü im OpenOffice.org-Fenster als auch über die Programmleiste des Betriebssystems erreichbar.
|}

= Eingeben von Programm-Code =

Löschen Sie folgende Zeilen:

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub
</code>

Schreiben Sie unterhalb der Zeile "Sub HelloWorld": <tt>msgbox "Hello World!"</tt>, so dass es in etwa so aussieht:

<code>[oobas]
Sub HelloWorld
msgbox "Hello World!"
End Sub
</code>

{| border="1"
|'''Achtung:'''
|Die IDE beherrscht zwar keine "code completion"(->dt.Auto-Vervollständigung), also die Fähigkeit eines Editors den Text automatisch zu vervollständigen, um den Schreibprozess zu beschleunigen, während der Eingabe, verfügt aber über eine kontext-sensitive Hilfe, wenn Sie während der Eingabe F1 oder "Hilfe" drücken oder der Cursor in einem Befehl steht. Bei OpenOffice.org Basic-Befehlen wird die Groß- und Kleinschreibung nicht unterschieden. So sind die Eingaben msgbox, MSGBOX oder Msgbox äquivalent. Strings (Textvariablen) werden in doppelte Anführrungszeichen eingeschlossen.
|-
|}

= Den Code ausführen =

Hierfür gibt es mehrere Möglichkeiten:

* direkt aus der IDE: das Symbol '''Ausführen''' (das 3. Symbol in der 2. Leiste) ruft das ERSTE Makro des aktuellen Moduls auf.
* aus dem Menü "Extras":
** (Version 1.1.x) '''Extras > Makros > Makro…''';
** (Version 1.9.x und höher) '''Extras > Makro > Makro auführen…'''
* Dem Makro ein Tastaturkürzel zuweisen (todo).
* Dem Makro einen Menüeintrag zuweisen (todo).
* Dem Makro ein Symbolleisten-Symbol zuweisen (todo).
* Ein Kontroll-Element in einem Dokument erstellen (todo).
* Das Makro einem Ereignis zuweisen (todo)

Führen Sie für den Anfang die "HelloWorld"-Subroutine aus, indem Sie auf das '''Ausführen'''-Symbol klicken. Ein kleiner Dialog mit dem Titel "soffice" und dem Text "Hello World" sollte aufpoppen.

= Speichern des Code =

Der Code wird immer automatisch gespeichert, wenn sein Container gespeichert wird. Wenn das Modul also in einer (allgemeinen oder benutzerspezifischen) OpenOffice.org-Bibliothek enthalten ist, wird es beim Schließen der Anwendung OpenOffice.org gespeichert. Entsprechend werden Dokument-interne Bibliotheken biem Speichern des Dokuments mit-gesichert.

Auf der Standard-Symbolleiste der IDE (normalerweise die oberste Symbolleiste) finden Sie ein Symbol "Speichern". Befindet sich der Code in einem Dokument oder einer Vorlage, dann speichert der Klick auf dieses Symbol das gesamte Dokument. Handelt es sich dagegen um eine OpenOffice.org-Bibliothek, wird nur die aktuelle Bibliothek gespeichert.

= Variablen =

Bei Variablen kann durch <tt>Option Explicit</tt> zu Beginn des Moduls die explizite Deklaration erzwungen werden. Zu Sinn und Unsinn des Deklarierens von Variablen lesen Sie [http://www.oooforum.org/forum/viewtopic.phtml?t=5845 diese Diskussion].

In dieser Diskussion vertritt der ursprüngliche Autor dieses Wiki-Beitrags die Position, dass Variablen immer deklariert werden sollten. Mittlerweile hat er seine Meinung geändert. Kurz: es ist eine Frage des persönlichen Geschmacks. Unabhängig davon sollten nach Auffassung des ursprünglichen Autors Variablen nach folgener Konvention benannt werden, die auch bei den Beispielen aus diesem Wiki verwendet wurde:

Der erste Buchstabe der Variable steht für den Typ des in der Variable gespeicherten Wertes. Dabei bezeichnen folgende Buchstaben die entsprechenden Datentypen (in Anlehung an das Tutorial.pdf von Sun):

{| border="1"
|'''''Buchstabe'''''
|'''''Bedeutung'''''
|-
|a
|Struktur (Structure)
|-
|b
|Bool'sch (WAHR oder FALSCH)
|-
|e
|Aufzählung (Enumeration). Diese Variable kann nur einen begrenzten Satz von Werten enthalten.
|-
|f
|Fließkomma-Zahl (3.402823 x 1038 bis 1.401298 x 10-45. Eine einzelne Variable kann bis zu 4 Bytes umfassen) "Double" (doppelte Genauigkeit, 1.79769313486232 x 10308 bis 4.94065645841247 x 10-324. Eine Double-Variable kann bis zu 8 Bytes umfassen) Währung (-922337203685477.5808 bis +922337203685477.5807 ebenfalls 8 Byte umfassend)
|-
|m
|Feld (Array) (aka Sequenz aka Matrix)
|-
|n
|Integer (-32768 to 32767.) oder Long (-2147483648 and 2147483647).
|-
|o
|Objekt, Service oder Interface
|-
|s
|Text (String) (Eine String-Variable kann bis zu 65535 Unicode-Zeichen enthalten).
|-
|x
|Schnittstelle (Interface), um anzuzeigen, dass nur Methoden einer bstimmten Schnittstelle eines Objekts verwendet werden.
|-
|v
|Variant, irgend ein Typ
|-
|}

Benutzen Sie lange, beschreibende Variablennamen unter Verwendung von CamelCase (Groß-Klein-Schreibung).

{| border="1"
|'''Achtung:'''
|Bei benutzerdefinierten OpenOffice.org Basic-Variablen spielt die Groß-/Kleinschreibunge keine Rolle. Bei UNO-API-Konstanten aber sehr wohl!
|}

Ausnahmen von der Regel, lange Namen zu verwenden, sind Index-Variablen (meist i, j oder k), sowie Strings (meist als s bezeichnet).

Bearbeiten Sie nun die sub HelloWorld, so dass der Code ungefähr wie im folgenden aussieht und führen Sie sie aus:

<code>[oobas]
sub HelloWorld
dim i as integer 'This line is optional
for i = 0 to 2
'These lines are indented for ease of reading only
'all your code should be like this for lonog time survival
msgbox "Hello World " & i
next i
end sub
</code>

Mehr Infos zur Verwendung von Variablen erhalten Sie in der Online-Hilfe unter "Variablen benutzen" (???)

= Die OpenOffice.org API =

Dieser Abschnitt beginnt mit einem Beispiel. Anschließend wird das Beispiel erläutert.

Versuchen Sie den folgenden Code in Dokumenten unterschiedlichen Typs auszuführen:

<code>[oobas]
sub main
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
msgbox fnWhichComponent(thisComponent)
end sub

function fnWhichComponent(oDoc) as string
if HasUnoInterfaces(oDoc, "com.sun.star.lang.XServiceInfo") then
if thisComponent.supportsService ("com.sun.star.text.GenericTextDocument") then
fnWhichComponent = "Text"
elseif thisComponent.supportsService("com.sun.star.sheet.SpreadsheetDocument") then
fnWhichComponent = "Spreadsheet"
elseif thisComponent.supportsService("com.sun.star.presentation.PresentationDocument") then
fnWhichComponent = "Presentation"
elseif thisComponent.supportsService("com.sun.star.drawing.GenericDrawingDocument") then
fnWhichComponent = "Drawing"
else
fnWhichComponent = "Oops current document something else"
end if
else
fnWhichComponent = "Not a document"
end if
End function
</code>

== Namenskonventionen für Subroutinen ==
im obigen Beispiel beginnt die Benutzer-definierte Funktion mit den Buchstaben "fn". Diese Konvention (an die sich der ursprüngliche Autor hält) kennzeichnet eine Funktion als Benutzer-definiert. Entsprechend beginnt eine Benutzer-definierte Subroutine mit "sub". Diese im Folgenden benutzten Konventionen sollen Ihnen als Anfängern helfen, Benutzer-definierte von eingebauten Routinen/Funktionen zu unterscheiden.

== Einführung in die OpenOffice.org API ==

In diesem Abschnitt werden folgende Begriffe erläutert:

* Interface (Schnittstelle)
* Modul
* Service (Dienst)
* Methode
* Property (Eigenschaft)

Den Unterschied zwischen einer Schnittstelle und einem Service zu kennen, ist zwar nicht unbedingt Voraussetzung zum Programmieren unter OpenOffice.org, aber es hilft, die Dokumentation zu verstehen, und auch bei der Introspektion. Möglicherweise werden Sie den folgenden Abschnitt mindestens zwei mal lesen müssen!

Eine Schnittstelle ist eine ''Definition'' eines Satzes von Methoden (und ihren Argumenten), die ein Dienst, der diese Schnittstelle implementiert, enthalten muss.

Schnittstellen werden aus Gründen der Namensgebung zu '''Modulen''' gruppiert. Alle Schnittstellen (und Dienste) beginnen mit <tt>com.sun.star</tt>, gefolgt vom Modul-Namen, dann kommt der Name der Schnittstelle (oder des Dienstes).

Beispielsweise bieten die meisten Dienste die Schnittstelle <tt>com.sun.star.beans.XPropertySet</tt>. Diese Schnittstelle ist im Modul <tt>beans</tt> gespeichert und ermöglicht Zugriff auf die Eigenschaften (Properties) eines Dienstes. Eine '''Eigenschaft''' ist ein Wert, eine '''Methode''' ist dagegen eine Aktion.

Ein OpenOffice.org-Objekt kann viele Dienste enthalten.

Ein OpenOffice.org-Objekt kann einen Dienst enthalten, der eine Schnittstelle implementiert, in welcher eine Methode beschreibt, dass ein anderes OpenOffice.org-Objekt zurückgegeben wird.

== Introspektion ==

'''HasUnoInterfaces''' ist eine OpenOffice.org-Basic-Funktion zur Introspektion. Informieren Sie sich über [http://www.oooforum.org/forum/viewtopic.phtml?t=7068 Introspektion in anderen Sprachen].

<tt>HasUnoInterfaces</tt> gibt <code>true</code> zurück, wenn beim spezifizierten Objekt alle spezifizierten Schnittstellen verfügbar sind.

Die meisten OpenOffice.org-Objekte enthalten die Methode '''supportsService''' weil sie die Schnittstelle <code>com.sun.star.lang.XServiceInfo</code> enthalten.

Im obigen Beispiel prüft <tt>HasUnoInterfaces</tt>, ob das aktuelle Dokument die Schnittstelle <tt>com.sun.star.lang.XServiceInfo</tt> implementiert, da andernfalls die Methode <tt>supportsService</tt> fehlen würde. Der Aufruf dieser Methode würde in diesem Fall einen Laufzeitfehler verursachen.

<tt>supportsService</tt> ist eine Methode, die den Wert <code>true</code> zurückgibt, wenn der spezifizierte Service verfügbar ist. Das obige Beispiel prüft das Vorhandensein eines Service, um so den Typ des aktuell aktiven Dokuments zu bestimmen.

== X-Ray tool ==
Die Benutzung von <tt>HasUnoInterfaces</tt> und <tt>supportsService</tt> reicht aus, um sich zur Laufzeit über ein Objekt zu informieren, aber zum Lernen eignet sich das [http://ooomacros.org/dev.php#101416 X-Ray tool von Bernard Marcelly] viel besser. Laden Sie das ZIP-File herunter, entpacken Sie es und öffnen Sie das enthaltene Dokument mit OpenOffice.org. Befolgen Sie anschließend die Installationsanweisungen.

Das '''X-Ray tool''' verlangt bei der Konfiguration eine lokale Kopie des OpenOffice.org SDK. Laden Sie es von [http://www.openoffice.org/dev_docs/source/sdk/ hier] herunter und entpacken Sie es.

Nun können Sie die beiden auskommentierten Zeilen des obigen Beispiels entkommentieren (den Apostroph entfernen):

<code>[oobas]
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
</code>

Führen Sie das Makro dann erneut aus.

Ab Xray Version 5 heißt das Kommando einfach '''xray'''.

'''BasicLibraries''' ist ein OpenOffice.org-Basic-Befehl, der ein Objekt zurückgibt, mit dem man auf die OpenOffice.org Bibliotheken zugreifen kann. Die Methode <tt>loadLibrary</tt> macht die Routinen aus dieser Bibliothek verfügbar.

<tt>xray.xray</tt> spezifiziert die Subroutine <tt>xray</tt> im Modul <tt>xray</tt> in dieser Bibliothek, <tt>thisComponent</tt> ist das Objekt, das an xray zur Introspektion übergeben wird.

Um mit einem bestimmten Objekt zu arbeiten erfordert häufig, dieses Objekt zu finden oder zu erzeugen, indem man mit <tt>StarDesktop</tt> oder <tt>thisComponent</tt> beginnt.

== Desktop, Dokumente, Selektionen ==
<tt>StarDesktop</tt> und <tt>ThisComponent</tt> sind OpenOffice.org-Basic-Befehle, die sich auf die Applikation bzw. das aktuell aktive Dokument beziehen.

Im Unterschied zu Microsoft Office ist OpenOffice.org eine Anwendung mit unterschiedlichen Komponenten. Beim Ausführen von Code möchte man häufig wissen, welche Komponente aktuell aktiv ist. Der obige Code zeigt eine Möglichkeit, dies zu überprüfen.

StarDesktop bezieht sich auf einen konzeptuellen Desktop (der historisch tatsächlich mal existiert hat) und meint de facto die Anwendung OpenOffice.org.

== Neue Dokumente erzeugen ==
Um ein neues Text-Dokument zu erzeugen:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/swriter", "_blank", 0, Array())
</code>
Um ein neues Tabellen-Dokument zu erzeugen:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/scalc", "_blank", 0, Array())
</code>
Ein sinnvoller Ansatz wäre, eine einfache Funktion zu schreiben:

<code>[oobas]
function fnNewDoc(sDocType as string)
fnNewDoc = StarDesktop.loadComponentFromURL("private:factory/" & sDocType , "_blank", 0, Array())
end function
</code>
Dann könnte man neue Dokumente ganz einfach erzeugen:

<code>[oobas]
oDoc = fnNewDoc("swriter")
oDoc = fnNewDoc("scalc")
oDoc = fnNewDoc("simpress")
oDoc = fnNewDoc("sdraw")
oDoc = fnNewDoc("smath")
</code>
Siehe http://api.openoffice.org/docs/common/ref/com/sun/star/frame/XComponentLoader.html .

== Ein bestehendes Dokument öffnen ==
Im folgenden Beispiel sehen Sie, wie Sie eine Datei öffnen können. OpenOffice.org URLs sind in [[DE: URL Grundlagen]] erläutert.

<code>[oobas]
sFile = "C:\Documents and Settings\danny\Desktop\MyCalc.sxc" ' Windows
sFile = "/home/danny/Desktop/MyCalc.sxc" ' Linux
sURL = ConvertToURL(sFile)
oDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
</code>
Auch hier könnte eine einfache Funktion das Schreiben verkürzen:

<code>[oobas]
function fnOpenDoc(sFile)
sURL = ConvertToURL(sFile)
fnOpenDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
end function
</code>
Beispiele für Aufrufe:

<code>[oobas]
oDoc = fnOpenDoc("C:\Documents and Settings\danny\Desktop\MyCalc.sxc") ' Windows
oDoc = fnOpenDoc("/home/danny/Desktop/MyCalc.sxc") ' Linux
</code>

== Die aktuelle Selektion ==
Häufig werden Sie eine Funktion schreiben wollen, die etwas mit dem aktuell selektierten Bereich anstellt. <tt>ThisComponent</tt> enthält die Methode <tt>getCurrentSelection</tt>. Da viele unterschiedliche Objekte selektiert sein könnten, werden Sie zuerst prüfen wollen, ob das selektierte Objekt über den Dienst verfügt, der die Methode enthält, mit der Sie das Objekt bearbeiten wollen.

Editieren Sie die Subroutine main im nachfolgenden Code und führen Sie sie mehrfach in einem Textdokument aus, wobei Sie unterschiedliche Objekte selektieren. (Um mehr als einen Textblock zu selektieren, betätigen Sie die '''Strg'''-Taste).

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
'xray.xray oCurSelection
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
msgbox "There are " & oCurSelection.getCount() & _
" selections in the current text document."
end if
end if
end sub
</code>
Wenn nichts selektiert ist, beträgt die Anzahl der Selektionen eins (nämlich der Einfügepunkt), wenn ein Textblock selektiert ist, beträgt die Anzahl ebenfalls eins, wenn zwei Textblöcke selektiert sind, beträgt sie drei: der Einfügepunkt sowie die beiden selektierten Textblöcke.

Übung 1: Modifizieren Sie den obigen Code so, dass er mit selektierten Zellbereichen in einem Tabellendokument funktioniert.

Frage 1: Wie hoch ist die Anzahl der Selektionen, wenn zwei Zellblöcke selektiert sind?

==Properties==
Wenn Sie die Zeile <tt>'xray.xray oCurSelection</tt> entkommentieren, so dass xray läuft, sehen Sie, dass das Objekt, worauf <tt>oCurSelection</tt> zeigt, eine "Property" namens <tt>Count</tt> besitzt, mit einer Beschreibung "pseudo-prop, read only". In OpenOffice.org Basic könnten Sie <tt>oCurSelection.count</tt> schreiben, da dies aber in keiner anderen Sprache, mit der Sie auf die OpenOffice.org API zugreifen können, möglich ist, werde ich versuchen, in diesem Wiki nur über Methoden zuzugreifen. (Möglicherweise vergesse ich das auch das eine oder andere Mal).

Das nächste Beispiel zeigt, wie man einen Property-Wert für die aktuellen Selektionen ändert.

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
nCount = oCurSelection.Count
'xray.xray oCurSelection.getByIndex(0)
'Warnung: Am Einfügepunkt wird die selbe Aktion zwei mal angewandt -
'das macht in diesem Fall nichts, kann aber durchaus problematisch werden.
for i = 0 to nCount - 1
oCurSelection.getByIndex(i).setPropertyValue("CharStyleName", "Strong Emphasis")
next
end if
end if
end sub
</code>

In OpenOffice.org Basic kann man die Zuweisung auch abkürzen:

<code>[oobas]
oCurSelection(i).CharStyleName = "Strong Emphasis"
</code>
Hier in diesem Wiki versuche ich, sowohl zur Indexierung als auch zur Zuweisung von Properties die vollständigen Methoden zu verwenden. Dadurch kann der Code leichter in andere Sprachen portiert werden und es hilft Ihnen auch, zu verstehen, was vor sich geht (nochmal: Bitte um Entschuldigung, wenn ich mal von dieser Regel abweiche, weil ich es eigentlich nicht gewohnt bin)

Übung 2: Schreiben Sie den obigen Code so um, dass die Warnung entfernt werden kann.

Siehe [[DE:Aktuelle Selektion]] ([[ Current selection]]).

=Iterative Access to Subordinate Objects (Enumeration access)=
Sometimes to access the desired object an enumeration is required. For example paragraphs, within a document or within a selection.

When a Writer document is active and some text is selected, both <tt>thisDocument.getText()</tt> and <tt>thisComponent.getCurrentSelection().getByIndex(i)</tt> have the service: com.sun.star.text.TextRange which has the interface: com.sun.star.container.XContentEnumerationAccess, it is possible to create an enumeration of the paragraphs for the current document or for a particular selection.

<code>[oobas]
' Create enumeration object
oTextElementEnum = thisComponent.getText().createEnumeration()
'or thisComponent.getCurrentSelection().getByIndex(i).createEnumeration()

' loop over all text elements
while oTextElementEnum.hasMoreElements()
oTextElement = oTextElementEnum.nextElement
if oTextElement.supportsService("com.sun.star.text.TextTable") then
MsgBox "The current block contains a table."
end if
if oTextElement.supportsService("com.sun.star.text.Paragraph") then
MsgBox "The current block contains a paragraph."
end if
wend
</code>
Exercise 3: Extend the above example to display in a message box all text portions that are bold.

=Named access=
Some objects provide named access to a particular type of subordinate object, some others indexed access, and some both named and indexed access.

For example if the current document in OpenOffice.org is a spreadsheet then to access a particular sheet can be done by index access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByIndex(0)
</code>
or named access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByName("Sheet1")
</code>
To check if an object with a particular name already exists use <tt>hasByName</tt>, for example:

<code>[oobas]
if thisComponent.getSheets.hasByName("Sheet1") then
</code>
To loop through all the available object names can be done like:

<code>[oobas]
mNames = thisComponent.getSheets.getElementnames
for i = lbound(mNames) to ubound(mNames)
msgbox mNames(i)
next
</code>

Some named subordinate objects also provide the interface: com.sun.star.container.XNameContainer. This interface defines that such objects should have the following methods: <tt>insertByName</tt>, <tt>replaceByname</tt> and <tt>removeByName</tt>.

E.g.

<code>[oobas]
thisComponent.getSheets.insertByName("NewSheet")
</code>

=Create new objects=
Some objects have services which implement interfaces to provide specific methods for creating a particular type of object.

For example if the current document is a Writer document then <tt>thisComponent.getText</tt> is an object that provides the service com.sun.star.text.Text which implements the interface com.sun.star.text.XSimpleText which defines the methods <tt>createTextCursor</tt> and <tt>createTextCursorByRange</tt>. Both of these methods create a text cursor for accessing the text of the document. These cursors are quite independent of the view cursor . The view cursor is visible on the screen and is manipulated by the user (and can be manipulated by program control), where as a text cursor is not visible on the screen and is solely used by program control. The following code snippet demonstrates creating a new text cursor, such that it starts at the same location as the viewCursor and is then moved independent of the view cursor.

<code>[oobas]
oVC = thisComponent.getCurrentController.getViewCursor
oCursor = oVC.getText.createTextCursorByRange(oVC)
oCursor.gotoStartOfSentence(false)
oCursor.gotoEndOfSentence(true)
msgbox oCursor.getString
</code>

Some objects are context dependent and get created using the method <tt>createInstance</tt> which is defined in the interface com.sun.star.lang.XMultiServiceFactory. For example to add a rectangle to the first page of a drawing document:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
dim aSize as new com.sun.star.awt.Size

aPoint.x = 1000
aPoint.y = 1000

aSize.Width = 10000
aSize.Height = 10000

oRectangleShape = thisComponent.createInstance("com.sun.star.drawing.RectangleShape")
oRectangleShape.Size = aSize
oRectangleShape.Position = aPoint

thisComponent.getDrawPages.getByIndex(0).add(oRectangleShape)
</code>

This example also uses UNO structs see below for more information on UNO stucts.

Some objects are context independent to create these objects use the OpenOffice.org Basic command createUnoService. For example to create the equivalent to StarDesktop:

<code>[oobas]
oDesktop = createUnoService("com.sun.star.frame.Desktop")
</code>

The process that I use to determine how to access or create an object is as follows:

Does the object already exist if so I should be able to access it from something like <tt>thisComponent</tt>.

Will the new object belong to another object, if so does the owner have a specific method for creating the object, if so use it.

The new object will belong to another object, but that object doesn't provide a specific method for creating it, but does provide <tt>createInstance</tt>. If the object doesn't provide <tt>createInstance</tt> are you sure you are using the correct object, or is it context independent.

I have found working out how to create an object to be quite difficult with existing documentation so I hope that this document/wiki will eventually make this clear.

==UNO structs==
UNO structures can be declared using the OpenOffice.org Basic command <tt>dim</tt>:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
</code>
Or by using the OpenOffice.org Basic command <tt>createUnoStruct</tt>:

<code>[oobas]
aPoint = createUnoStruct("com.sun.star.awt.Point")
</code>

{| border="1"
|'''Note:'''
|When declaring UNO structs case is important. Note that everything upto the name of the struct is lowercase, and that the name of the struct is in TitleCase.
|}

==Creating Listeners and Handlers==
Through the user interface it is possible to assign macros to some events:

OpenOffice.org versions 1.1.x: '''Tools > Configure… > Events'''.

OpenOffice.org versions 1.9.x and above: '''Tools > Customize… > Events'''.

It is also possible to assign macros to a wider range of events using the OpenOffice.org Basic command CreateUnoListener. This same command is used for creating both listeners and handlers. A listener checks for an event and always allows other listeners to respond to the event as well. A handler listens for an event, and can optionally consume the event so that other listeners don't get to act on it.

The following example creates a keyHandler:

<code>[oobas]
global IannzExampleKeyHandler

sub SetupKeyHandler
oController = thisComponent.currentController
IannzExampleKeyHandler = CreateUnoListener("KeyHandler_","com.sun.star.awt.XKeyHandler")
oController.addKeyHandler(IannzExampleKeyHandler) ' Register the listener
end sub

sub RemoveKeyHandler
thisComponent.currentController.removeKeyHandler(IannzExampleKeyHandler)
end sub

sub KeyHandler_disposing
end sub

function KeyHandler_keyReleased(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyReleased = False
end function

function KeyHandler_keyPressed(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyPressed = false 'Let other listeners handle the event
if oKeyEvent.modifiers = com.sun.star.awt.KeyModifier.MOD2 then 'Control key was pressed
if oKeyEvent.keyCode = com.sun.star.awt.Key.Q then
msgbox "Alt + Q was pressed"
KeyHandler_keyPressed = true 'Don't let other listeners process this event
end if
end if
end function
</code>
A variable declared as global keeps its value even after the macro exits. In this case we want to be able to use this variable later to remove the handler. As variables declared globally could be used in other libraries to try and avoid conflict I start all my global variables with Iannz my registered name for the OpenOffice.org web site.

<tt>sub SetupKeyHandler</tt> sets up the handler. The first parameter to CreateUnoListener is the staring name for the methods that will be called when that type of event occurs in this example .<tt>"KeyHandler_"</tt>.

The second parameter is the name of the interface for the listener or handler, "com.sun.star.awt.XKeyHandler". The name is case sensitive, everything up to and including the module name is always lowercase, the name of the interface always starts with "X" and the remainder is in TitleCase.

Use the SDK to find out what methods the interface must supply. You must supply routines for all of these methods even if you don't intend to use them. You also need to supply a disposing method. The names of these routines start with the string given in the first parameter to CreateUnoListener , in this example <tt>"KeyHandler_"</tt>.

Thus in the example there is <tt>KeyHandler_disposing</tt> and <tt>KeyHandler_keyReleased</tt> which don't actually do anything but are required, and <tt>KeyHandler_keyPressed</tt> which actually does the job.

<tt>sub RemoveKeyHandler</tt> demonstrates how to remove the handler.

=OpenOffice.org constants=
The above example uses OpenOffice.org constants.

E.g. com.sun.star.awt.KeyModifier.MOD2

OpenOffice.org constants are case sensitive. Everything up to and including the module name is always lowercase. The constant group is in TitleCase. The actual constant name is always UPPERCASE.

Programmers not using OpenOffice.org Basic may not have access to these constants.

=Using the recorder=
See [[ The OpenOffice.org recorder and UNO dispatch calls]] section for a discussion on recording UNO Dispatch commands versus writing API calls.

[[Category:Basic:Tutorials]]

DE/Makro Basic Tutorial

2006-09-06T01:03:02Z

Global667: /* Eingeben von Programm-Code */

[[Category:de.openoffice.org|Makro Basic Tutorial]]

{| cellspacing=0 cellpadding=5 style="border: 1px solid black;"
| bgcolor=orange colspan=2 |'''Achtung, work in progress'''
Dieses Dokument wird gerade übersetzt, wer mag, darf auch gerne helfen.
|-
|'''Arbeitstitel:''' || "Einführung: Basic für OOo-Erweiterungen"
|-
|'''Originaldokument:''' || [[Extensions_development_basic]] 
|-
|'''Ursprünglicher Autor:''' || Ian Laurenson
|-
| offene Fragen: || sind mit ??? gekennzeichnet
|}

Diese Seite soll Ihnen eine Einführung in das Schreiben von Makros mit OpenOffice.org Basic geben. Grundkenntnisse im Programmieren werden vorausgesetzt. Bitte fühlen Sie sich frei, diese Seite zu editieren, um sie lesbarer zu machen. Ich hoffe, das Sie Ihnen von Nutzen sein wird.

Wenn Sie bereits mit den Grundlagen vertraut sind, können Sie sich auch direkt im KochBuch ([[CookBook]]) Wrapper (Hüllfunktionen ???) und Beispiele anschauen.

= Wohin schreibe ich den Code? =

Der Basic-Code wird bei OpenOffice.org in '''Modulen''' gespeichert, die in '''Bibliotheken''' zusammengefasst sind.

Eine Bibliothek kann
* '''allgemein''', also für die gesamte (Netzwerk-) Installation verfügbar sein ("OOo Makros und Dialoge")
* nur für den aktuellen '''Benutzer''' verfügbar sein ("Meine Makros und Dialoge")
* in einem '''Dokument''' oder in einer Vorlage abgelegt sein, so dass ihr Code nur zur Verfügung steht, wenn das Dokument geöffnet ist.
Bibliotheken, die nicht in einem Dokument abgelegt sind (also allgemein oder für den aktuellen Benutzer verfügbare Bibliotheken) werden im Folgenden als ''OpenOffice.org Bibliotheken'' zusammengefasst.

Der physische Speicherort für diese OpenOffice.org Bibliotheken wird unter '''Extras > Optionen… > OpenOffice.org > Pfade > BASIC''' festgelegt.

{| border="1"
|'''Anmerkung:'''
|Hüten Sie sich, Bibliotheken auf Dateisystem-Ebene zu verschieben oder zu kopieren. Benutzen Sie stattdessen den Dialog "Makros verwalten" oder den Paket-Manager
|}

Module in Bibliotheken können maximal 64kb groß sein. Eine Bibliothek kann bis zu 16 000 Module enthalten. Weitere Infos finden Sie in der Online-Hilfe unter "Module und Bibliotheken" (???).

= Die Entwicklungsumgebung (IDE) =

Öffnen Sie die Entwicklungsumgebung:
* in OOo 1.1.x unter '''Extras > Makros > Makro ...'''
* in OOo 1.9.x und höher unter ''' Extras > Makros > Makros verwalten > OpenOffice.org Basic...'''

Zum Einstieg benutzen wir das "Modul1" aus der Bibliothek "Standard" des aktuellen Benutzers:

Geben Sie einen Namen für das neue Makro ein: "HelloWorld"

Wählen Sie die Option '''Standard''' im Auswahlfeld "Makro aus:"

Klicken Sie auf '''Neu'''

Jetzt sollten Sie etwa folgendes sehen:

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub

Sub HelloWorld

End Sub
</code>

Der Cursor sollte am Anfang der Zeile <tt>Sub HelloWorld</tt> stehen.

{| border="1"
|'''Achtung:'''
|Das geöffnete IDE-Fenster ist sowohl über das Menü im OpenOffice.org-Fenster als auch über die Programmleiste des Betriebssystems erreichbar.
|}

= Eingeben von Programm-Code =

Löschen Sie folgende Zeilen:

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub
</code>

Schreiben Sie unterhalb der Zeile "Sub HelloWorld": <tt>msgbox "Hello World!"</tt>, so dass es in etwa so aussieht:

<code>[oobas]
Sub HelloWorld
msgbox "Hello World!"
End Sub
</code>

{| border="1"
|'''Achtung:'''
|Die IDE beherrscht zwar keine "code completion"(->dt.Auto-Vervollständigung), also die Fähigkeit eines Editors den Text automatisch zu vervollständigen, um den Schreibprozess zu beschleunigen, während der Eingabe, verfügt aber über eine kontext-sensitive Hilfe, wenn Sie während der Eingabe F1 oder "Hilfe" drücken oder der Cursor in einem Befehl steht. Bei OpenOffice.org Basic-Befehlen wird die Groß- und Kleinschreibung nicht unterschieden. So sind die Eingaben msgbox, MSGBOX oder Msgbox äquivalent. Strings (Textvariablen) werden in doppelte Anführrungszeichen eingeschlossen.
|-
|}

= Den Code ausführen =

Hierfür gibt es mehrere Möglichkeiten:

* direkt aus der IDE: das Symbol '''Ausführen''' (das 3. Symbol in der 2. Leiste) ruft das ERSTE Makro des aktuellen Moduls auf.
* aus dem Menü "Extras":
** (Version 1.1.x) '''Extras > Makros > Makro…''';
** (Version 1.9.x und höher) '''Extras > Makro > Makro auführen…'''
* Dem Makro ein Tastaturkürzel zuweisen (todo).
* Dem Makro einen Menüeintrag zuweisen (todo).
* Dem Makro ein Symbolleisten-Symbol zuweisen (todo).
* Ein Kontroll-Element in einem Dokument erstellen (todo).
* Das Makro einem Ereignis zuweisen (todo)

Führen Sie für den Anfang die "HelloWorld"-Subroutine aus, indem Sie auf das '''Ausführen'''-Symbol klicken. Ein kleiner Dialog mit dem Titel "soffice" und dem Text "Hello World" sollte aufpoppen.

= Speichern des Code =

Der Code wird immer automatisch gespeichert, wenn sein Container gespeichert wird. Wenn das Modul also in einer (allgemeinen oder benutzerspezifischen) OpenOffice.org-Bibliothek enthalten ist, wird es beim Schließen der Anwendung OpenOffice.org gespeichert. Entsprechend werden Dokument-interne Bibliotheken biem Speichern des Dokuments mit-gesichert.

Auf der Standard-Symbolleiste der IDE (normalerweise die oberste Symbolleiste) finden Sie ein Symbol "Speichern". Befindet sich der Code in einem Dokument oder einer Vorlage, dann speichert der Klick auf dieses Symbol das gesamte Dokument. Handelt es sich dagegen um eine OpenOffice.org-Bibliothek, wird nur die aktuelle Bibliothek gespeichert.

= Variablen =

Bei Variablen kann durch <tt>Option Explicit</tt> zu Beginn des Moduls die explizite Deklaration erzwungen werden. Zu Sinn und Unsinn des Deklarierens von Variablen lesen Sie [http://www.oooforum.org/forum/viewtopic.phtml?t=5845 diese Diskussion].

In dieser Diskussion vertritt der ursprüngliche Autor dieses Wiki-Beitrags die Position, dass Variablen immer deklariert werden sollten. Mittlerweile hat er seine Meinung geändert. Kurz: es ist eine Frage des persönlichen Geschmacks. Unabhängig davon sollten nach Auffassung des ursprünglichen Autors Variablen nach folgener Konvention benannt werden, die auch bei den Beispielen aus diesem Wiki verwendet wurde:

Der erste Buchstabe der Variable steht für den Typ des in der Variable gespeicherten Wertes. Dabei bezeichnen folgende Buchstaben die entsprechenden Datentypen (in Anlehung an das Tutorial.pdf von Sun):

{| border="1"
|'''''Buchstabe'''''
|'''''Bedeutung'''''
|-
|a
|Struktur (Structure)
|-
|b
|Bool'sch (WAHR oder FALSCH)
|-
|e
|Aufzählung (Enumeration). Diese Variable kann nur einen begrenzten Satz von Werten enthalten.
|-
|f
|Fließkomma-Zahl (3.402823 x 1038 bis 1.401298 x 10-45. Eine einzelne Variable kann bis zu 4 Bytes umfassen) "Double" (doppelte Genauigkeit, 1.79769313486232 x 10308 bis 4.94065645841247 x 10-324. Eine Double-Variable kann bis zu 8 Bytes umfassen) Währung (-922337203685477.5808 bis +922337203685477.5807 ebenfalls 8 Byte umfassend)
|-
|m
|Feld (Array) (aka Sequenz aka Matrix)
|-
|n
|Integer (-32768 to 32767.) oder Long (-2147483648 and 2147483647).
|-
|o
|Objekt, Service oder Interface
|-
|s
|Text (String) (Eine String-Variable kann bis zu 65535 Unicode-Zeichen enthalten).
|-
|x
|Schnittstelle (Interface), um anzuzeigen, dass nur Methoden einer bstimmten Schnittstelle eines Objekts verwendet werden.
|-
|v
|Variant, irgend ein Typ
|-
|}

Benutzen Sie lange, beschreibende Variablennamen unter Verwendung von CamelCase (Groß-Klein-Schreibung).

{| border="1"
|'''Achtung:'''
|Bei benutzerdefinierten OpenOffice.org Basic-Variablen spielt die Groß-/Kleinschreibunge keine Rolle. Bei UNO-API-Konstanten aber sehr wohl!
|}

Ausnahmen von der Regel, lange Namen zu verwenden, sind Index-Variablen (meist i, j oder k), sowie Strings (meist als s bezeichnet).

Bearbeiten Sie nun die sub HelloWorld, so dass der Code ungefähr wie im folgenden aussieht und führen Sie sie aus:

<code>[oobas]
sub HelloWorld
dim i as integer 'This line is optional
for i = 0 to 2
'These lines are indented for ease of reading only
'all your code should be like this for lonog time survival
msgbox "Hello World " & i
next i
end sub
</code>

Mehr Infos zur Verwendung von Variablen erhalten Sie in der Online-Hilfe unter "Variablen benutzen" (???)

= Die OpenOffice.org API =

Dieser Abschnitt beginnt mit einem Beispiel. Anschließend wird das Beispiel erläutert.

Versuchen Sie den folgenden Code in Dokumenten unterschiedlichen Typs auszuführen:

<code>[oobas]
sub main
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
msgbox fnWhichComponent(thisComponent)
end sub

function fnWhichComponent(oDoc) as string
if HasUnoInterfaces(oDoc, "com.sun.star.lang.XServiceInfo") then
if thisComponent.supportsService ("com.sun.star.text.GenericTextDocument") then
fnWhichComponent = "Text"
elseif thisComponent.supportsService("com.sun.star.sheet.SpreadsheetDocument") then
fnWhichComponent = "Spreadsheet"
elseif thisComponent.supportsService("com.sun.star.presentation.PresentationDocument") then
fnWhichComponent = "Presentation"
elseif thisComponent.supportsService("com.sun.star.drawing.GenericDrawingDocument") then
fnWhichComponent = "Drawing"
else
fnWhichComponent = "Oops current document something else"
end if
else
fnWhichComponent = "Not a document"
end if
End function
</code>

== Namenskonventionen für Subroutinen ==
im obigen Beispiel beginnt die Benutzer-definierte Funktion mit den Buchstaben "fn". Diese Konvention (an die sich der ursprüngliche Autor hält) kennzeichnet eine Funktion als Benutzer-definiert. Entsprechend beginnt eine Benutzer-definierte Subroutine mit "sub". Diese im Folgenden benutzten Konventionen sollen Ihnen als Anfängern helfen, Benutzer-definierte von eingebauten Routinen/Funktionen zu unterscheiden.

== Einführung in die OpenOffice.org API ==

In diesem Abschnitt werden folgende Begriffe erläutert:

* Interface (Schnittstelle)
* Modul
* Service (Dienst)
* Methode
* Property (Eigenschaft)

Den Unterschied zwischen einer Schnittstelle und einem Service zu kennen, ist zwar nicht unbedingt Voraussetzung zum Programmieren unter OpenOffice.org, aber es hilft, die Dokumentation zu verstehen, und auch bei der Introspektion. Möglicherweise werden Sie den folgenden Abschnitt mindestens zwei mal lesen müssen!

Eine Schnittstelle ist eine ''Definition'' eines Satzes von Methoden (und ihren Argumenten), die ein Dienst, der diese Schnittstelle implementiert, enthalten muss.

Schnittstellen werden aus Gründen der Namensgebung zu '''Modulen''' gruppiert. Alle Schnittstellen (und Dienste) beginnen mit <tt>com.sun.star</tt>, gefolgt vom Modul-Namen, dann kommt der Name der Schnittstelle (oder des Dienstes).

Beispielsweise bieten die meisten Dienste die Schnittstelle <tt>com.sun.star.beans.XPropertySet</tt>. Diese Schnittstelle ist im Modul <tt>beans</tt> gespeichert und ermöglicht Zugriff auf die Eigenschaften (Properties) eines Dienstes. Eine '''Eigenschaft''' ist ein Wert, eine '''Methode''' ist dagegen eine Aktion.

Ein OpenOffice.org-Objekt kann viele Dienste enthalten.

Ein OpenOffice.org-Objekt kann einen Dienst enthalten, der eine Schnittstelle implementiert, in welcher eine Methode beschreibt, dass ein anderes OpenOffice.org-Objekt zurückgegeben wird.

== Introspektion ==

'''HasUnoInterfaces''' ist eine OpenOffice.org-Basic-Funktion zur Introspektion. Informieren Sie sich über [http://www.oooforum.org/forum/viewtopic.phtml?t=7068 Introspektion in anderen Sprachen].

<tt>HasUnoInterfaces</tt> gibt <code>true</code> zurück, wenn beim spezifizierten Objekt alle spezifizierten Schnittstellen verfügbar sind.

Die meisten OpenOffice.org-Objekte enthalten die Methode '''supportsService''' weil sie die Schnittstelle <code>com.sun.star.lang.XServiceInfo</code> enthalten.

Im obigen Beispiel prüft <tt>HasUnoInterfaces</tt>, ob das aktuelle Dokument die Schnittstelle <tt>com.sun.star.lang.XServiceInfo</tt> implementiert, da andernfalls die Methode <tt>supportsService</tt> fehlen würde. Der Aufruf dieser Methode würde in diesem Fall einen Laufzeitfehler verursachen.

<tt>supportsService</tt> ist eine Methode, die den Wert <code>true</code> zurückgibt, wenn der spezifizierte Service verfügbar ist. Das obige Beispiel prüft das Vorhandensein eines Service, um so den Typ des aktuell aktiven Dokuments zu bestimmen.

== X-Ray tool ==
Die Benutzung von <tt>HasUnoInterfaces</tt> und <tt>supportsService</tt> reicht aus, um sich zur Laufzeit über ein Objekt zu informieren, aber zum Lernen eignet sich das [http://ooomacros.org/dev.php#101416 X-Ray tool von Bernard Marcelly] viel besser. Laden Sie das ZIP-File herunter, entpacken Sie es und öffnen Sie das enthaltene Dokument mit OpenOffice.org. Befolgen Sie anschließend die Installationsanweisungen.

Das '''X-Ray tool''' verlangt bei der Konfiguration eine lokale Kopie des OpenOffice.org SDK. Laden Sie es von ??? herunter und entpacken Sie es.

Nun können Sie die beiden auskommentierten Zeilen des obigen Beispiels entkommentieren (den Apostroph entfernen):

<code>[oobas]
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
</code>

Führen Sie das Makro dann erneut aus.

Ab Xray Version 5 heißt das Kommando einfach '''xray'''.

'''BasicLibraries''' ist ein OpenOffice.org-Basic-Befehl, der ein Objekt zurückgibt, mit dem man auf die OpenOffice.org Bibliotheken zugreifen kann. Die Methode <tt>loadLibrary</tt> macht die Routinen aus dieser Bibliothek verfügbar.

<tt>xray.xray</tt> spezifiziert die Subroutine <tt>xray</tt> im Modul <tt>xray</tt> in dieser Bibliothek, <tt>thisComponent</tt> ist das Objekt, das an xray zur Introspektion übergeben wird.

Um mit einem bestimmten Objekt zu arbeiten erfordert häufig, dieses Objekt zu finden oder zu erzeugen, indem man mit <tt>StarDesktop</tt> oder <tt>thisComponent</tt> beginnt.

== Desktop, Dokumente, Selektionen ==
<tt>StarDesktop</tt> und <tt>ThisComponent</tt> sind OpenOffice.org-Basic-Befehle, die sich auf die Applikation bzw. das aktuell aktive Dokument beziehen.

Im Unterschied zu Microsoft Office ist OpenOffice.org eine Anwendung mit unterschiedlichen Komponenten. Beim Ausführen von Code möchte man häufig wissen, welche Komponente aktuell aktiv ist. Der obige Code zeigt eine Möglichkeit, dies zu überprüfen.

StarDesktop bezieht sich auf einen konzeptuellen Desktop (der historisch tatsächlich mal existiert hat) und meint de facto die Anwendung OpenOffice.org.

== Neue Dokumente erzeugen ==
Um ein neues Text-Dokument zu erzeugen:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/swriter", "_blank", 0, Array())
</code>
Um ein neues Tabellen-Dokument zu erzeugen:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/scalc", "_blank", 0, Array())
</code>
Ein sinnvoller Ansatz wäre, eine einfache Funktion zu schreiben:

<code>[oobas]
function fnNewDoc(sDocType as string)
fnNewDoc = StarDesktop.loadComponentFromURL("private:factory/" & sDocType , "_blank", 0, Array())
end function
</code>
Dann könnte man neue Dokumente ganz einfach erzeugen:

<code>[oobas]
oDoc = fnNewDoc("swriter")
oDoc = fnNewDoc("scalc")
oDoc = fnNewDoc("simpress")
oDoc = fnNewDoc("sdraw")
oDoc = fnNewDoc("smath")
</code>
Siehe http://api.openoffice.org/docs/common/ref/com/sun/star/frame/XComponentLoader.html .

== Ein bestehendes Dokument öffnen ==
Im folgenden Beispiel sehen Sie, wie Sie eine Datei öffnen können. OpenOffice.org URLs sind in [[DE: URL Grundlagen]] erläutert.

<code>[oobas]
sFile = "C:\Documents and Settings\danny\Desktop\MyCalc.sxc" ' Windows
sFile = "/home/danny/Desktop/MyCalc.sxc" ' Linux
sURL = ConvertToURL(sFile)
oDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
</code>
Auch hier könnte eine einfache Funktion das Schreiben verkürzen:

<code>[oobas]
function fnOpenDoc(sFile)
sURL = ConvertToURL(sFile)
fnOpenDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
end function
</code>
Beispiele für Aufrufe:

<code>[oobas]
oDoc = fnOpenDoc("C:\Documents and Settings\danny\Desktop\MyCalc.sxc") ' Windows
oDoc = fnOpenDoc("/home/danny/Desktop/MyCalc.sxc") ' Linux
</code>

== Die aktuelle Selektion ==
Häufig werden Sie eine Funktion schreiben wollen, die etwas mit dem aktuell selektierten Bereich anstellt. <tt>ThisComponent</tt> enthält die Methode <tt>getCurrentSelection</tt>. Da viele unterschiedliche Objekte selektiert sein könnten, werden Sie zuerst prüfen wollen, ob das selektierte Objekt über den Dienst verfügt, der die Methode enthält, mit der Sie das Objekt bearbeiten wollen.

Editieren Sie die Subroutine main im nachfolgenden Code und führen Sie sie mehrfach in einem Textdokument aus, wobei Sie unterschiedliche Objekte selektieren. (Um mehr als einen Textblock zu selektieren, betätigen Sie die '''Strg'''-Taste).

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
'xray.xray oCurSelection
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
msgbox "There are " & oCurSelection.getCount() & _
" selections in the current text document."
end if
end if
end sub
</code>
Wenn nichts selektiert ist, beträgt die Anzahl der Selektionen eins (nämlich der Einfügepunkt), wenn ein Textblock selektiert ist, beträgt die Anzahl ebenfalls eins, wenn zwei Textblöcke selektiert sind, beträgt sie drei: der Einfügepunkt sowie die beiden selektierten Textblöcke.

Übung 1: Modifizieren Sie den obigen Code so, dass er mit selektierten Zellbereichen in einem Tabellendokument funktioniert.

Frage 1: Wie hoch ist die Anzahl der Selektionen, wenn zwei Zellblöcke selektiert sind?

==Properties==
Wenn Sie die Zeile <tt>'xray.xray oCurSelection</tt> entkommentieren, so dass xray läuft, sehen Sie, dass das Objekt, worauf <tt>oCurSelection</tt> zeigt, eine "Property" namens <tt>Count</tt> besitzt, mit einer Beschreibung "pseudo-prop, read only". In OpenOffice.org Basic könnten Sie <tt>oCurSelection.count</tt> schreiben, da dies aber in keiner anderen Sprache, mit der Sie auf die OpenOffice.org API zugreifen können, möglich ist, werde ich versuchen, in diesem Wiki nur über Methoden zuzugreifen. (Möglicherweise vergesse ich das auch das eine oder andere Mal).

Das nächste Beispiel zeigt, wie man einen Property-Wert für die aktuellen Selektionen ändert.

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
nCount = oCurSelection.Count
'xray.xray oCurSelection.getByIndex(0)
'Warnung: Am Einfügepunkt wird die selbe Aktion zwei mal angewandt -
'das macht in diesem Fall nichts, kann aber durchaus problematisch werden.
for i = 0 to nCount - 1
oCurSelection.getByIndex(i).setPropertyValue("CharStyleName", "Strong Emphasis")
next
end if
end if
end sub
</code>

In OpenOffice.org Basic kann man die Zuweisung auch abkürzen:

<code>[oobas]
oCurSelection(i).CharStyleName = "Strong Emphasis"
</code>
Hier in diesem Wiki versuche ich, sowohl zur Indexierung als auch zur Zuweisung von Properties die vollständigen Methoden zu verwenden. Dadurch kann der Code leichter in andere Sprachen portiert werden und es hilft Ihnen auch, zu verstehen, was vor sich geht (nochmal: Bitte um Entschuldigung, wenn ich mal von dieser Regel abweiche, weil ich es eigentlich nicht gewohnt bin)

Übung 2: Schreiben Sie den obigen Code so um, dass die Warnung entfernt werden kann.

Siehe [[DE:Aktuelle Selektion]] ([[ Current selection]]).

=Iterative Access to Subordinate Objects (Enumeration access)=
Sometimes to access the desired object an enumeration is required. For example paragraphs, within a document or within a selection.

When a Writer document is active and some text is selected, both <tt>thisDocument.getText()</tt> and <tt>thisComponent.getCurrentSelection().getByIndex(i)</tt> have the service: com.sun.star.text.TextRange which has the interface: com.sun.star.container.XContentEnumerationAccess, it is possible to create an enumeration of the paragraphs for the current document or for a particular selection.

<code>[oobas]
' Create enumeration object
oTextElementEnum = thisComponent.getText().createEnumeration()
'or thisComponent.getCurrentSelection().getByIndex(i).createEnumeration()

' loop over all text elements
while oTextElementEnum.hasMoreElements()
oTextElement = oTextElementEnum.nextElement
if oTextElement.supportsService("com.sun.star.text.TextTable") then
MsgBox "The current block contains a table."
end if
if oTextElement.supportsService("com.sun.star.text.Paragraph") then
MsgBox "The current block contains a paragraph."
end if
wend
</code>
Exercise 3: Extend the above example to display in a message box all text portions that are bold.

=Named access=
Some objects provide named access to a particular type of subordinate object, some others indexed access, and some both named and indexed access.

For example if the current document in OpenOffice.org is a spreadsheet then to access a particular sheet can be done by index access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByIndex(0)
</code>
or named access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByName("Sheet1")
</code>
To check if an object with a particular name already exists use <tt>hasByName</tt>, for example:

<code>[oobas]
if thisComponent.getSheets.hasByName("Sheet1") then
</code>
To loop through all the available object names can be done like:

<code>[oobas]
mNames = thisComponent.getSheets.getElementnames
for i = lbound(mNames) to ubound(mNames)
msgbox mNames(i)
next
</code>

Some named subordinate objects also provide the interface: com.sun.star.container.XNameContainer. This interface defines that such objects should have the following methods: <tt>insertByName</tt>, <tt>replaceByname</tt> and <tt>removeByName</tt>.

E.g.

<code>[oobas]
thisComponent.getSheets.insertByName("NewSheet")
</code>

=Create new objects=
Some objects have services which implement interfaces to provide specific methods for creating a particular type of object.

For example if the current document is a Writer document then <tt>thisComponent.getText</tt> is an object that provides the service com.sun.star.text.Text which implements the interface com.sun.star.text.XSimpleText which defines the methods <tt>createTextCursor</tt> and <tt>createTextCursorByRange</tt>. Both of these methods create a text cursor for accessing the text of the document. These cursors are quite independent of the view cursor . The view cursor is visible on the screen and is manipulated by the user (and can be manipulated by program control), where as a text cursor is not visible on the screen and is solely used by program control. The following code snippet demonstrates creating a new text cursor, such that it starts at the same location as the viewCursor and is then moved independent of the view cursor.

<code>[oobas]
oVC = thisComponent.getCurrentController.getViewCursor
oCursor = oVC.getText.createTextCursorByRange(oVC)
oCursor.gotoStartOfSentence(false)
oCursor.gotoEndOfSentence(true)
msgbox oCursor.getString
</code>

Some objects are context dependent and get created using the method <tt>createInstance</tt> which is defined in the interface com.sun.star.lang.XMultiServiceFactory. For example to add a rectangle to the first page of a drawing document:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
dim aSize as new com.sun.star.awt.Size

aPoint.x = 1000
aPoint.y = 1000

aSize.Width = 10000
aSize.Height = 10000

oRectangleShape = thisComponent.createInstance("com.sun.star.drawing.RectangleShape")
oRectangleShape.Size = aSize
oRectangleShape.Position = aPoint

thisComponent.getDrawPages.getByIndex(0).add(oRectangleShape)
</code>

This example also uses UNO structs see below for more information on UNO stucts.

Some objects are context independent to create these objects use the OpenOffice.org Basic command createUnoService. For example to create the equivalent to StarDesktop:

<code>[oobas]
oDesktop = createUnoService("com.sun.star.frame.Desktop")
</code>

The process that I use to determine how to access or create an object is as follows:

Does the object already exist if so I should be able to access it from something like <tt>thisComponent</tt>.

Will the new object belong to another object, if so does the owner have a specific method for creating the object, if so use it.

The new object will belong to another object, but that object doesn't provide a specific method for creating it, but does provide <tt>createInstance</tt>. If the object doesn't provide <tt>createInstance</tt> are you sure you are using the correct object, or is it context independent.

I have found working out how to create an object to be quite difficult with existing documentation so I hope that this document/wiki will eventually make this clear.

==UNO structs==
UNO structures can be declared using the OpenOffice.org Basic command <tt>dim</tt>:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
</code>
Or by using the OpenOffice.org Basic command <tt>createUnoStruct</tt>:

<code>[oobas]
aPoint = createUnoStruct("com.sun.star.awt.Point")
</code>

{| border="1"
|'''Note:'''
|When declaring UNO structs case is important. Note that everything upto the name of the struct is lowercase, and that the name of the struct is in TitleCase.
|}

==Creating Listeners and Handlers==
Through the user interface it is possible to assign macros to some events:

OpenOffice.org versions 1.1.x: '''Tools > Configure… > Events'''.

OpenOffice.org versions 1.9.x and above: '''Tools > Customize… > Events'''.

It is also possible to assign macros to a wider range of events using the OpenOffice.org Basic command CreateUnoListener. This same command is used for creating both listeners and handlers. A listener checks for an event and always allows other listeners to respond to the event as well. A handler listens for an event, and can optionally consume the event so that other listeners don't get to act on it.

The following example creates a keyHandler:

<code>[oobas]
global IannzExampleKeyHandler

sub SetupKeyHandler
oController = thisComponent.currentController
IannzExampleKeyHandler = CreateUnoListener("KeyHandler_","com.sun.star.awt.XKeyHandler")
oController.addKeyHandler(IannzExampleKeyHandler) ' Register the listener
end sub

sub RemoveKeyHandler
thisComponent.currentController.removeKeyHandler(IannzExampleKeyHandler)
end sub

sub KeyHandler_disposing
end sub

function KeyHandler_keyReleased(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyReleased = False
end function

function KeyHandler_keyPressed(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyPressed = false 'Let other listeners handle the event
if oKeyEvent.modifiers = com.sun.star.awt.KeyModifier.MOD2 then 'Control key was pressed
if oKeyEvent.keyCode = com.sun.star.awt.Key.Q then
msgbox "Alt + Q was pressed"
KeyHandler_keyPressed = true 'Don't let other listeners process this event
end if
end if
end function
</code>
A variable declared as global keeps its value even after the macro exits. In this case we want to be able to use this variable later to remove the handler. As variables declared globally could be used in other libraries to try and avoid conflict I start all my global variables with Iannz my registered name for the OpenOffice.org web site.

<tt>sub SetupKeyHandler</tt> sets up the handler. The first parameter to CreateUnoListener is the staring name for the methods that will be called when that type of event occurs in this example .<tt>"KeyHandler_"</tt>.

The second parameter is the name of the interface for the listener or handler, "com.sun.star.awt.XKeyHandler". The name is case sensitive, everything up to and including the module name is always lowercase, the name of the interface always starts with "X" and the remainder is in TitleCase.

Use the SDK to find out what methods the interface must supply. You must supply routines for all of these methods even if you don't intend to use them. You also need to supply a disposing method. The names of these routines start with the string given in the first parameter to CreateUnoListener , in this example <tt>"KeyHandler_"</tt>.

Thus in the example there is <tt>KeyHandler_disposing</tt> and <tt>KeyHandler_keyReleased</tt> which don't actually do anything but are required, and <tt>KeyHandler_keyPressed</tt> which actually does the job.

<tt>sub RemoveKeyHandler</tt> demonstrates how to remove the handler.

=OpenOffice.org constants=
The above example uses OpenOffice.org constants.

E.g. com.sun.star.awt.KeyModifier.MOD2

OpenOffice.org constants are case sensitive. Everything up to and including the module name is always lowercase. The constant group is in TitleCase. The actual constant name is always UPPERCASE.

Programmers not using OpenOffice.org Basic may not have access to these constants.

=Using the recorder=
See [[ The OpenOffice.org recorder and UNO dispatch calls]] section for a discussion on recording UNO Dispatch commands versus writing API calls.

[[Category:Basic:Tutorials]]

DE/Makro Basic Tutorial

2006-09-06T01:01:38Z

Global667: /* Eingeben von Programm-Code */

[[Category:de.openoffice.org|Makro Basic Tutorial]]

{| cellspacing=0 cellpadding=5 style="border: 1px solid black;"
| bgcolor=orange colspan=2 |'''Achtung, work in progress'''
Dieses Dokument wird gerade übersetzt, wer mag, darf auch gerne helfen.
|-
|'''Arbeitstitel:''' || "Einführung: Basic für OOo-Erweiterungen"
|-
|'''Originaldokument:''' || [[Extensions_development_basic]] 
|-
|'''Ursprünglicher Autor:''' || Ian Laurenson
|-
| offene Fragen: || sind mit ??? gekennzeichnet
|}

Diese Seite soll Ihnen eine Einführung in das Schreiben von Makros mit OpenOffice.org Basic geben. Grundkenntnisse im Programmieren werden vorausgesetzt. Bitte fühlen Sie sich frei, diese Seite zu editieren, um sie lesbarer zu machen. Ich hoffe, das Sie Ihnen von Nutzen sein wird.

Wenn Sie bereits mit den Grundlagen vertraut sind, können Sie sich auch direkt im KochBuch ([[CookBook]]) Wrapper (Hüllfunktionen ???) und Beispiele anschauen.

= Wohin schreibe ich den Code? =

Der Basic-Code wird bei OpenOffice.org in '''Modulen''' gespeichert, die in '''Bibliotheken''' zusammengefasst sind.

Eine Bibliothek kann
* '''allgemein''', also für die gesamte (Netzwerk-) Installation verfügbar sein ("OOo Makros und Dialoge")
* nur für den aktuellen '''Benutzer''' verfügbar sein ("Meine Makros und Dialoge")
* in einem '''Dokument''' oder in einer Vorlage abgelegt sein, so dass ihr Code nur zur Verfügung steht, wenn das Dokument geöffnet ist.
Bibliotheken, die nicht in einem Dokument abgelegt sind (also allgemein oder für den aktuellen Benutzer verfügbare Bibliotheken) werden im Folgenden als ''OpenOffice.org Bibliotheken'' zusammengefasst.

Der physische Speicherort für diese OpenOffice.org Bibliotheken wird unter '''Extras > Optionen… > OpenOffice.org > Pfade > BASIC''' festgelegt.

{| border="1"
|'''Anmerkung:'''
|Hüten Sie sich, Bibliotheken auf Dateisystem-Ebene zu verschieben oder zu kopieren. Benutzen Sie stattdessen den Dialog "Makros verwalten" oder den Paket-Manager
|}

Module in Bibliotheken können maximal 64kb groß sein. Eine Bibliothek kann bis zu 16 000 Module enthalten. Weitere Infos finden Sie in der Online-Hilfe unter "Module und Bibliotheken" (???).

= Die Entwicklungsumgebung (IDE) =

Öffnen Sie die Entwicklungsumgebung:
* in OOo 1.1.x unter '''Extras > Makros > Makro ...'''
* in OOo 1.9.x und höher unter ''' Extras > Makros > Makros verwalten > OpenOffice.org Basic...'''

Zum Einstieg benutzen wir das "Modul1" aus der Bibliothek "Standard" des aktuellen Benutzers:

Geben Sie einen Namen für das neue Makro ein: "HelloWorld"

Wählen Sie die Option '''Standard''' im Auswahlfeld "Makro aus:"

Klicken Sie auf '''Neu'''

Jetzt sollten Sie etwa folgendes sehen:

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub

Sub HelloWorld

End Sub
</code>

Der Cursor sollte am Anfang der Zeile <tt>Sub HelloWorld</tt> stehen.

{| border="1"
|'''Achtung:'''
|Das geöffnete IDE-Fenster ist sowohl über das Menü im OpenOffice.org-Fenster als auch über die Programmleiste des Betriebssystems erreichbar.
|}

= Eingeben von Programm-Code =

Löschen Sie folgende Zeilen:

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub
</code>

Schreiben Sie unterhalb der Zeile "Sub HelloWorld": <tt>msgbox "Hello World!"</tt>, so dass es in etwa so aussieht:

<code>[oobas]
Sub HelloWorld
msgbox "Hello World!"
End Sub
</code>

{| border="1"
|'''Achtung:'''
|Die IDE beherrscht zwar keine "code completion"(->dt.Auto-Vervollständigung), also die Fähigkeit eines Editors den Text automatisch zu vervollständigen um den Schreibprozess zu beschleunigen, während der Eingabe, verfügt aber über eine kontext-sensitive Hilfe, wenn Sie während der Eingabe F1 oder "Hilfe" drücken oder der Cursor in einem Befehl steht. Bei OpenOffice.org Basic-Befehlen wird die Groß- und Kleinschreibung nicht unterschieden. So sind die Eingaben msgbox, MSGBOX oder Msgbox äquivalent. Stings (Textvariablen) werden in doppelte Anfürhrungszeichen eingeschlossen.
|-
|}

= Den Code ausführen =

Hierfür gibt es mehrere Möglichkeiten:

* direkt aus der IDE: das Symbol '''Ausführen''' (das 3. Symbol in der 2. Leiste) ruft das ERSTE Makro des aktuellen Moduls auf.
* aus dem Menü "Extras":
** (Version 1.1.x) '''Extras > Makros > Makro…''';
** (Version 1.9.x und höher) '''Extras > Makro > Makro auführen…'''
* Dem Makro ein Tastaturkürzel zuweisen (todo).
* Dem Makro einen Menüeintrag zuweisen (todo).
* Dem Makro ein Symbolleisten-Symbol zuweisen (todo).
* Ein Kontroll-Element in einem Dokument erstellen (todo).
* Das Makro einem Ereignis zuweisen (todo)

Führen Sie für den Anfang die "HelloWorld"-Subroutine aus, indem Sie auf das '''Ausführen'''-Symbol klicken. Ein kleiner Dialog mit dem Titel "soffice" und dem Text "Hello World" sollte aufpoppen.

= Speichern des Code =

Der Code wird immer automatisch gespeichert, wenn sein Container gespeichert wird. Wenn das Modul also in einer (allgemeinen oder benutzerspezifischen) OpenOffice.org-Bibliothek enthalten ist, wird es beim Schließen der Anwendung OpenOffice.org gespeichert. Entsprechend werden Dokument-interne Bibliotheken biem Speichern des Dokuments mit-gesichert.

Auf der Standard-Symbolleiste der IDE (normalerweise die oberste Symbolleiste) finden Sie ein Symbol "Speichern". Befindet sich der Code in einem Dokument oder einer Vorlage, dann speichert der Klick auf dieses Symbol das gesamte Dokument. Handelt es sich dagegen um eine OpenOffice.org-Bibliothek, wird nur die aktuelle Bibliothek gespeichert.

= Variablen =

Bei Variablen kann durch <tt>Option Explicit</tt> zu Beginn des Moduls die explizite Deklaration erzwungen werden. Zu Sinn und Unsinn des Deklarierens von Variablen lesen Sie [http://www.oooforum.org/forum/viewtopic.phtml?t=5845 diese Diskussion].

In dieser Diskussion vertritt der ursprüngliche Autor dieses Wiki-Beitrags die Position, dass Variablen immer deklariert werden sollten. Mittlerweile hat er seine Meinung geändert. Kurz: es ist eine Frage des persönlichen Geschmacks. Unabhängig davon sollten nach Auffassung des ursprünglichen Autors Variablen nach folgener Konvention benannt werden, die auch bei den Beispielen aus diesem Wiki verwendet wurde:

Der erste Buchstabe der Variable steht für den Typ des in der Variable gespeicherten Wertes. Dabei bezeichnen folgende Buchstaben die entsprechenden Datentypen (in Anlehung an das Tutorial.pdf von Sun):

{| border="1"
|'''''Buchstabe'''''
|'''''Bedeutung'''''
|-
|a
|Struktur (Structure)
|-
|b
|Bool'sch (WAHR oder FALSCH)
|-
|e
|Aufzählung (Enumeration). Diese Variable kann nur einen begrenzten Satz von Werten enthalten.
|-
|f
|Fließkomma-Zahl (3.402823 x 1038 bis 1.401298 x 10-45. Eine einzelne Variable kann bis zu 4 Bytes umfassen) "Double" (doppelte Genauigkeit, 1.79769313486232 x 10308 bis 4.94065645841247 x 10-324. Eine Double-Variable kann bis zu 8 Bytes umfassen) Währung (-922337203685477.5808 bis +922337203685477.5807 ebenfalls 8 Byte umfassend)
|-
|m
|Feld (Array) (aka Sequenz aka Matrix)
|-
|n
|Integer (-32768 to 32767.) oder Long (-2147483648 and 2147483647).
|-
|o
|Objekt, Service oder Interface
|-
|s
|Text (String) (Eine String-Variable kann bis zu 65535 Unicode-Zeichen enthalten).
|-
|x
|Schnittstelle (Interface), um anzuzeigen, dass nur Methoden einer bstimmten Schnittstelle eines Objekts verwendet werden.
|-
|v
|Variant, irgend ein Typ
|-
|}

Benutzen Sie lange, beschreibende Variablennamen unter Verwendung von CamelCase (Groß-Klein-Schreibung).

{| border="1"
|'''Achtung:'''
|Bei benutzerdefinierten OpenOffice.org Basic-Variablen spielt die Groß-/Kleinschreibunge keine Rolle. Bei UNO-API-Konstanten aber sehr wohl!
|}

Ausnahmen von der Regel, lange Namen zu verwenden, sind Index-Variablen (meist i, j oder k), sowie Strings (meist als s bezeichnet).

Bearbeiten Sie nun die sub HelloWorld, so dass der Code ungefähr wie im folgenden aussieht und führen Sie sie aus:

<code>[oobas]
sub HelloWorld
dim i as integer 'This line is optional
for i = 0 to 2
'These lines are indented for ease of reading only
'all your code should be like this for lonog time survival
msgbox "Hello World " & i
next i
end sub
</code>

Mehr Infos zur Verwendung von Variablen erhalten Sie in der Online-Hilfe unter "Variablen benutzen" (???)

= Die OpenOffice.org API =

Dieser Abschnitt beginnt mit einem Beispiel. Anschließend wird das Beispiel erläutert.

Versuchen Sie den folgenden Code in Dokumenten unterschiedlichen Typs auszuführen:

<code>[oobas]
sub main
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
msgbox fnWhichComponent(thisComponent)
end sub

function fnWhichComponent(oDoc) as string
if HasUnoInterfaces(oDoc, "com.sun.star.lang.XServiceInfo") then
if thisComponent.supportsService ("com.sun.star.text.GenericTextDocument") then
fnWhichComponent = "Text"
elseif thisComponent.supportsService("com.sun.star.sheet.SpreadsheetDocument") then
fnWhichComponent = "Spreadsheet"
elseif thisComponent.supportsService("com.sun.star.presentation.PresentationDocument") then
fnWhichComponent = "Presentation"
elseif thisComponent.supportsService("com.sun.star.drawing.GenericDrawingDocument") then
fnWhichComponent = "Drawing"
else
fnWhichComponent = "Oops current document something else"
end if
else
fnWhichComponent = "Not a document"
end if
End function
</code>

== Namenskonventionen für Subroutinen ==
im obigen Beispiel beginnt die Benutzer-definierte Funktion mit den Buchstaben "fn". Diese Konvention (an die sich der ursprüngliche Autor hält) kennzeichnet eine Funktion als Benutzer-definiert. Entsprechend beginnt eine Benutzer-definierte Subroutine mit "sub". Diese im Folgenden benutzten Konventionen sollen Ihnen als Anfängern helfen, Benutzer-definierte von eingebauten Routinen/Funktionen zu unterscheiden.

== Einführung in die OpenOffice.org API ==

In diesem Abschnitt werden folgende Begriffe erläutert:

* Interface (Schnittstelle)
* Modul
* Service (Dienst)
* Methode
* Property (Eigenschaft)

Den Unterschied zwischen einer Schnittstelle und einem Service zu kennen, ist zwar nicht unbedingt Voraussetzung zum Programmieren unter OpenOffice.org, aber es hilft, die Dokumentation zu verstehen, und auch bei der Introspektion. Möglicherweise werden Sie den folgenden Abschnitt mindestens zwei mal lesen müssen!

Eine Schnittstelle ist eine ''Definition'' eines Satzes von Methoden (und ihren Argumenten), die ein Dienst, der diese Schnittstelle implementiert, enthalten muss.

Schnittstellen werden aus Gründen der Namensgebung zu '''Modulen''' gruppiert. Alle Schnittstellen (und Dienste) beginnen mit <tt>com.sun.star</tt>, gefolgt vom Modul-Namen, dann kommt der Name der Schnittstelle (oder des Dienstes).

Beispielsweise bieten die meisten Dienste die Schnittstelle <tt>com.sun.star.beans.XPropertySet</tt>. Diese Schnittstelle ist im Modul <tt>beans</tt> gespeichert und ermöglicht Zugriff auf die Eigenschaften (Properties) eines Dienstes. Eine '''Eigenschaft''' ist ein Wert, eine '''Methode''' ist dagegen eine Aktion.

Ein OpenOffice.org-Objekt kann viele Dienste enthalten.

Ein OpenOffice.org-Objekt kann einen Dienst enthalten, der eine Schnittstelle implementiert, in welcher eine Methode beschreibt, dass ein anderes OpenOffice.org-Objekt zurückgegeben wird.

== Introspektion ==

'''HasUnoInterfaces''' ist eine OpenOffice.org-Basic-Funktion zur Introspektion. Informieren Sie sich über [http://www.oooforum.org/forum/viewtopic.phtml?t=7068 Introspektion in anderen Sprachen].

<tt>HasUnoInterfaces</tt> gibt <code>true</code> zurück, wenn beim spezifizierten Objekt alle spezifizierten Schnittstellen verfügbar sind.

Die meisten OpenOffice.org-Objekte enthalten die Methode '''supportsService''' weil sie die Schnittstelle <code>com.sun.star.lang.XServiceInfo</code> enthalten.

Im obigen Beispiel prüft <tt>HasUnoInterfaces</tt>, ob das aktuelle Dokument die Schnittstelle <tt>com.sun.star.lang.XServiceInfo</tt> implementiert, da andernfalls die Methode <tt>supportsService</tt> fehlen würde. Der Aufruf dieser Methode würde in diesem Fall einen Laufzeitfehler verursachen.

<tt>supportsService</tt> ist eine Methode, die den Wert <code>true</code> zurückgibt, wenn der spezifizierte Service verfügbar ist. Das obige Beispiel prüft das Vorhandensein eines Service, um so den Typ des aktuell aktiven Dokuments zu bestimmen.

== X-Ray tool ==
Die Benutzung von <tt>HasUnoInterfaces</tt> und <tt>supportsService</tt> reicht aus, um sich zur Laufzeit über ein Objekt zu informieren, aber zum Lernen eignet sich das [http://ooomacros.org/dev.php#101416 X-Ray tool von Bernard Marcelly] viel besser. Laden Sie das ZIP-File herunter, entpacken Sie es und öffnen Sie das enthaltene Dokument mit OpenOffice.org. Befolgen Sie anschließend die Installationsanweisungen.

Das '''X-Ray tool''' verlangt bei der Konfiguration eine lokale Kopie des OpenOffice.org SDK. Laden Sie es von ??? herunter und entpacken Sie es.

Nun können Sie die beiden auskommentierten Zeilen des obigen Beispiels entkommentieren (den Apostroph entfernen):

<code>[oobas]
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
</code>

Führen Sie das Makro dann erneut aus.

Ab Xray Version 5 heißt das Kommando einfach '''xray'''.

'''BasicLibraries''' ist ein OpenOffice.org-Basic-Befehl, der ein Objekt zurückgibt, mit dem man auf die OpenOffice.org Bibliotheken zugreifen kann. Die Methode <tt>loadLibrary</tt> macht die Routinen aus dieser Bibliothek verfügbar.

<tt>xray.xray</tt> spezifiziert die Subroutine <tt>xray</tt> im Modul <tt>xray</tt> in dieser Bibliothek, <tt>thisComponent</tt> ist das Objekt, das an xray zur Introspektion übergeben wird.

Um mit einem bestimmten Objekt zu arbeiten erfordert häufig, dieses Objekt zu finden oder zu erzeugen, indem man mit <tt>StarDesktop</tt> oder <tt>thisComponent</tt> beginnt.

== Desktop, Dokumente, Selektionen ==
<tt>StarDesktop</tt> und <tt>ThisComponent</tt> sind OpenOffice.org-Basic-Befehle, die sich auf die Applikation bzw. das aktuell aktive Dokument beziehen.

Im Unterschied zu Microsoft Office ist OpenOffice.org eine Anwendung mit unterschiedlichen Komponenten. Beim Ausführen von Code möchte man häufig wissen, welche Komponente aktuell aktiv ist. Der obige Code zeigt eine Möglichkeit, dies zu überprüfen.

StarDesktop bezieht sich auf einen konzeptuellen Desktop (der historisch tatsächlich mal existiert hat) und meint de facto die Anwendung OpenOffice.org.

== Neue Dokumente erzeugen ==
Um ein neues Text-Dokument zu erzeugen:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/swriter", "_blank", 0, Array())
</code>
Um ein neues Tabellen-Dokument zu erzeugen:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/scalc", "_blank", 0, Array())
</code>
Ein sinnvoller Ansatz wäre, eine einfache Funktion zu schreiben:

<code>[oobas]
function fnNewDoc(sDocType as string)
fnNewDoc = StarDesktop.loadComponentFromURL("private:factory/" & sDocType , "_blank", 0, Array())
end function
</code>
Dann könnte man neue Dokumente ganz einfach erzeugen:

<code>[oobas]
oDoc = fnNewDoc("swriter")
oDoc = fnNewDoc("scalc")
oDoc = fnNewDoc("simpress")
oDoc = fnNewDoc("sdraw")
oDoc = fnNewDoc("smath")
</code>
Siehe http://api.openoffice.org/docs/common/ref/com/sun/star/frame/XComponentLoader.html .

== Ein bestehendes Dokument öffnen ==
Im folgenden Beispiel sehen Sie, wie Sie eine Datei öffnen können. OpenOffice.org URLs sind in [[DE: URL Grundlagen]] erläutert.

<code>[oobas]
sFile = "C:\Documents and Settings\danny\Desktop\MyCalc.sxc" ' Windows
sFile = "/home/danny/Desktop/MyCalc.sxc" ' Linux
sURL = ConvertToURL(sFile)
oDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
</code>
Auch hier könnte eine einfache Funktion das Schreiben verkürzen:

<code>[oobas]
function fnOpenDoc(sFile)
sURL = ConvertToURL(sFile)
fnOpenDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
end function
</code>
Beispiele für Aufrufe:

<code>[oobas]
oDoc = fnOpenDoc("C:\Documents and Settings\danny\Desktop\MyCalc.sxc") ' Windows
oDoc = fnOpenDoc("/home/danny/Desktop/MyCalc.sxc") ' Linux
</code>

== Die aktuelle Selektion ==
Häufig werden Sie eine Funktion schreiben wollen, die etwas mit dem aktuell selektierten Bereich anstellt. <tt>ThisComponent</tt> enthält die Methode <tt>getCurrentSelection</tt>. Da viele unterschiedliche Objekte selektiert sein könnten, werden Sie zuerst prüfen wollen, ob das selektierte Objekt über den Dienst verfügt, der die Methode enthält, mit der Sie das Objekt bearbeiten wollen.

Editieren Sie die Subroutine main im nachfolgenden Code und führen Sie sie mehrfach in einem Textdokument aus, wobei Sie unterschiedliche Objekte selektieren. (Um mehr als einen Textblock zu selektieren, betätigen Sie die '''Strg'''-Taste).

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
'xray.xray oCurSelection
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
msgbox "There are " & oCurSelection.getCount() & _
" selections in the current text document."
end if
end if
end sub
</code>
Wenn nichts selektiert ist, beträgt die Anzahl der Selektionen eins (nämlich der Einfügepunkt), wenn ein Textblock selektiert ist, beträgt die Anzahl ebenfalls eins, wenn zwei Textblöcke selektiert sind, beträgt sie drei: der Einfügepunkt sowie die beiden selektierten Textblöcke.

Übung 1: Modifizieren Sie den obigen Code so, dass er mit selektierten Zellbereichen in einem Tabellendokument funktioniert.

Frage 1: Wie hoch ist die Anzahl der Selektionen, wenn zwei Zellblöcke selektiert sind?

==Properties==
Wenn Sie die Zeile <tt>'xray.xray oCurSelection</tt> entkommentieren, so dass xray läuft, sehen Sie, dass das Objekt, worauf <tt>oCurSelection</tt> zeigt, eine "Property" namens <tt>Count</tt> besitzt, mit einer Beschreibung "pseudo-prop, read only". In OpenOffice.org Basic könnten Sie <tt>oCurSelection.count</tt> schreiben, da dies aber in keiner anderen Sprache, mit der Sie auf die OpenOffice.org API zugreifen können, möglich ist, werde ich versuchen, in diesem Wiki nur über Methoden zuzugreifen. (Möglicherweise vergesse ich das auch das eine oder andere Mal).

Das nächste Beispiel zeigt, wie man einen Property-Wert für die aktuellen Selektionen ändert.

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
nCount = oCurSelection.Count
'xray.xray oCurSelection.getByIndex(0)
'Warnung: Am Einfügepunkt wird die selbe Aktion zwei mal angewandt -
'das macht in diesem Fall nichts, kann aber durchaus problematisch werden.
for i = 0 to nCount - 1
oCurSelection.getByIndex(i).setPropertyValue("CharStyleName", "Strong Emphasis")
next
end if
end if
end sub
</code>

In OpenOffice.org Basic kann man die Zuweisung auch abkürzen:

<code>[oobas]
oCurSelection(i).CharStyleName = "Strong Emphasis"
</code>
Hier in diesem Wiki versuche ich, sowohl zur Indexierung als auch zur Zuweisung von Properties die vollständigen Methoden zu verwenden. Dadurch kann der Code leichter in andere Sprachen portiert werden und es hilft Ihnen auch, zu verstehen, was vor sich geht (nochmal: Bitte um Entschuldigung, wenn ich mal von dieser Regel abweiche, weil ich es eigentlich nicht gewohnt bin)

Übung 2: Schreiben Sie den obigen Code so um, dass die Warnung entfernt werden kann.

Siehe [[DE:Aktuelle Selektion]] ([[ Current selection]]).

=Iterative Access to Subordinate Objects (Enumeration access)=
Sometimes to access the desired object an enumeration is required. For example paragraphs, within a document or within a selection.

When a Writer document is active and some text is selected, both <tt>thisDocument.getText()</tt> and <tt>thisComponent.getCurrentSelection().getByIndex(i)</tt> have the service: com.sun.star.text.TextRange which has the interface: com.sun.star.container.XContentEnumerationAccess, it is possible to create an enumeration of the paragraphs for the current document or for a particular selection.

<code>[oobas]
' Create enumeration object
oTextElementEnum = thisComponent.getText().createEnumeration()
'or thisComponent.getCurrentSelection().getByIndex(i).createEnumeration()

' loop over all text elements
while oTextElementEnum.hasMoreElements()
oTextElement = oTextElementEnum.nextElement
if oTextElement.supportsService("com.sun.star.text.TextTable") then
MsgBox "The current block contains a table."
end if
if oTextElement.supportsService("com.sun.star.text.Paragraph") then
MsgBox "The current block contains a paragraph."
end if
wend
</code>
Exercise 3: Extend the above example to display in a message box all text portions that are bold.

=Named access=
Some objects provide named access to a particular type of subordinate object, some others indexed access, and some both named and indexed access.

For example if the current document in OpenOffice.org is a spreadsheet then to access a particular sheet can be done by index access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByIndex(0)
</code>
or named access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByName("Sheet1")
</code>
To check if an object with a particular name already exists use <tt>hasByName</tt>, for example:

<code>[oobas]
if thisComponent.getSheets.hasByName("Sheet1") then
</code>
To loop through all the available object names can be done like:

<code>[oobas]
mNames = thisComponent.getSheets.getElementnames
for i = lbound(mNames) to ubound(mNames)
msgbox mNames(i)
next
</code>

Some named subordinate objects also provide the interface: com.sun.star.container.XNameContainer. This interface defines that such objects should have the following methods: <tt>insertByName</tt>, <tt>replaceByname</tt> and <tt>removeByName</tt>.

E.g.

<code>[oobas]
thisComponent.getSheets.insertByName("NewSheet")
</code>

=Create new objects=
Some objects have services which implement interfaces to provide specific methods for creating a particular type of object.

For example if the current document is a Writer document then <tt>thisComponent.getText</tt> is an object that provides the service com.sun.star.text.Text which implements the interface com.sun.star.text.XSimpleText which defines the methods <tt>createTextCursor</tt> and <tt>createTextCursorByRange</tt>. Both of these methods create a text cursor for accessing the text of the document. These cursors are quite independent of the view cursor . The view cursor is visible on the screen and is manipulated by the user (and can be manipulated by program control), where as a text cursor is not visible on the screen and is solely used by program control. The following code snippet demonstrates creating a new text cursor, such that it starts at the same location as the viewCursor and is then moved independent of the view cursor.

<code>[oobas]
oVC = thisComponent.getCurrentController.getViewCursor
oCursor = oVC.getText.createTextCursorByRange(oVC)
oCursor.gotoStartOfSentence(false)
oCursor.gotoEndOfSentence(true)
msgbox oCursor.getString
</code>

Some objects are context dependent and get created using the method <tt>createInstance</tt> which is defined in the interface com.sun.star.lang.XMultiServiceFactory. For example to add a rectangle to the first page of a drawing document:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
dim aSize as new com.sun.star.awt.Size

aPoint.x = 1000
aPoint.y = 1000

aSize.Width = 10000
aSize.Height = 10000

oRectangleShape = thisComponent.createInstance("com.sun.star.drawing.RectangleShape")
oRectangleShape.Size = aSize
oRectangleShape.Position = aPoint

thisComponent.getDrawPages.getByIndex(0).add(oRectangleShape)
</code>

This example also uses UNO structs see below for more information on UNO stucts.

Some objects are context independent to create these objects use the OpenOffice.org Basic command createUnoService. For example to create the equivalent to StarDesktop:

<code>[oobas]
oDesktop = createUnoService("com.sun.star.frame.Desktop")
</code>

The process that I use to determine how to access or create an object is as follows:

Does the object already exist if so I should be able to access it from something like <tt>thisComponent</tt>.

Will the new object belong to another object, if so does the owner have a specific method for creating the object, if so use it.

The new object will belong to another object, but that object doesn't provide a specific method for creating it, but does provide <tt>createInstance</tt>. If the object doesn't provide <tt>createInstance</tt> are you sure you are using the correct object, or is it context independent.

I have found working out how to create an object to be quite difficult with existing documentation so I hope that this document/wiki will eventually make this clear.

==UNO structs==
UNO structures can be declared using the OpenOffice.org Basic command <tt>dim</tt>:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
</code>
Or by using the OpenOffice.org Basic command <tt>createUnoStruct</tt>:

<code>[oobas]
aPoint = createUnoStruct("com.sun.star.awt.Point")
</code>

{| border="1"
|'''Note:'''
|When declaring UNO structs case is important. Note that everything upto the name of the struct is lowercase, and that the name of the struct is in TitleCase.
|}

==Creating Listeners and Handlers==
Through the user interface it is possible to assign macros to some events:

OpenOffice.org versions 1.1.x: '''Tools > Configure… > Events'''.

OpenOffice.org versions 1.9.x and above: '''Tools > Customize… > Events'''.

It is also possible to assign macros to a wider range of events using the OpenOffice.org Basic command CreateUnoListener. This same command is used for creating both listeners and handlers. A listener checks for an event and always allows other listeners to respond to the event as well. A handler listens for an event, and can optionally consume the event so that other listeners don't get to act on it.

The following example creates a keyHandler:

<code>[oobas]
global IannzExampleKeyHandler

sub SetupKeyHandler
oController = thisComponent.currentController
IannzExampleKeyHandler = CreateUnoListener("KeyHandler_","com.sun.star.awt.XKeyHandler")
oController.addKeyHandler(IannzExampleKeyHandler) ' Register the listener
end sub

sub RemoveKeyHandler
thisComponent.currentController.removeKeyHandler(IannzExampleKeyHandler)
end sub

sub KeyHandler_disposing
end sub

function KeyHandler_keyReleased(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyReleased = False
end function

function KeyHandler_keyPressed(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyPressed = false 'Let other listeners handle the event
if oKeyEvent.modifiers = com.sun.star.awt.KeyModifier.MOD2 then 'Control key was pressed
if oKeyEvent.keyCode = com.sun.star.awt.Key.Q then
msgbox "Alt + Q was pressed"
KeyHandler_keyPressed = true 'Don't let other listeners process this event
end if
end if
end function
</code>
A variable declared as global keeps its value even after the macro exits. In this case we want to be able to use this variable later to remove the handler. As variables declared globally could be used in other libraries to try and avoid conflict I start all my global variables with Iannz my registered name for the OpenOffice.org web site.

<tt>sub SetupKeyHandler</tt> sets up the handler. The first parameter to CreateUnoListener is the staring name for the methods that will be called when that type of event occurs in this example .<tt>"KeyHandler_"</tt>.

The second parameter is the name of the interface for the listener or handler, "com.sun.star.awt.XKeyHandler". The name is case sensitive, everything up to and including the module name is always lowercase, the name of the interface always starts with "X" and the remainder is in TitleCase.

Use the SDK to find out what methods the interface must supply. You must supply routines for all of these methods even if you don't intend to use them. You also need to supply a disposing method. The names of these routines start with the string given in the first parameter to CreateUnoListener , in this example <tt>"KeyHandler_"</tt>.

Thus in the example there is <tt>KeyHandler_disposing</tt> and <tt>KeyHandler_keyReleased</tt> which don't actually do anything but are required, and <tt>KeyHandler_keyPressed</tt> which actually does the job.

<tt>sub RemoveKeyHandler</tt> demonstrates how to remove the handler.

=OpenOffice.org constants=
The above example uses OpenOffice.org constants.

E.g. com.sun.star.awt.KeyModifier.MOD2

OpenOffice.org constants are case sensitive. Everything up to and including the module name is always lowercase. The constant group is in TitleCase. The actual constant name is always UPPERCASE.

Programmers not using OpenOffice.org Basic may not have access to these constants.

=Using the recorder=
See [[ The OpenOffice.org recorder and UNO dispatch calls]] section for a discussion on recording UNO Dispatch commands versus writing API calls.

[[Category:Basic:Tutorials]]

DE/Makro Basic Tutorial

2006-09-06T00:57:53Z

Global667: /* Wohin schreibe ich den Code? */

[[Category:de.openoffice.org|Makro Basic Tutorial]]

{| cellspacing=0 cellpadding=5 style="border: 1px solid black;"
| bgcolor=orange colspan=2 |'''Achtung, work in progress'''
Dieses Dokument wird gerade übersetzt, wer mag, darf auch gerne helfen.
|-
|'''Arbeitstitel:''' || "Einführung: Basic für OOo-Erweiterungen"
|-
|'''Originaldokument:''' || [[Extensions_development_basic]] 
|-
|'''Ursprünglicher Autor:''' || Ian Laurenson
|-
| offene Fragen: || sind mit ??? gekennzeichnet
|}

Diese Seite soll Ihnen eine Einführung in das Schreiben von Makros mit OpenOffice.org Basic geben. Grundkenntnisse im Programmieren werden vorausgesetzt. Bitte fühlen Sie sich frei, diese Seite zu editieren, um sie lesbarer zu machen. Ich hoffe, das Sie Ihnen von Nutzen sein wird.

Wenn Sie bereits mit den Grundlagen vertraut sind, können Sie sich auch direkt im KochBuch ([[CookBook]]) Wrapper (Hüllfunktionen ???) und Beispiele anschauen.

= Wohin schreibe ich den Code? =

Der Basic-Code wird bei OpenOffice.org in '''Modulen''' gespeichert, die in '''Bibliotheken''' zusammengefasst sind.

Eine Bibliothek kann
* '''allgemein''', also für die gesamte (Netzwerk-) Installation verfügbar sein ("OOo Makros und Dialoge")
* nur für den aktuellen '''Benutzer''' verfügbar sein ("Meine Makros und Dialoge")
* in einem '''Dokument''' oder in einer Vorlage abgelegt sein, so dass ihr Code nur zur Verfügung steht, wenn das Dokument geöffnet ist.
Bibliotheken, die nicht in einem Dokument abgelegt sind (also allgemein oder für den aktuellen Benutzer verfügbare Bibliotheken) werden im Folgenden als ''OpenOffice.org Bibliotheken'' zusammengefasst.

Der physische Speicherort für diese OpenOffice.org Bibliotheken wird unter '''Extras > Optionen… > OpenOffice.org > Pfade > BASIC''' festgelegt.

{| border="1"
|'''Anmerkung:'''
|Hüten Sie sich, Bibliotheken auf Dateisystem-Ebene zu verschieben oder zu kopieren. Benutzen Sie stattdessen den Dialog "Makros verwalten" oder den Paket-Manager
|}

Module in Bibliotheken können maximal 64kb groß sein. Eine Bibliothek kann bis zu 16 000 Module enthalten. Weitere Infos finden Sie in der Online-Hilfe unter "Module und Bibliotheken" (???).

= Die Entwicklungsumgebung (IDE) =

Öffnen Sie die Entwicklungsumgebung:
* in OOo 1.1.x unter '''Extras > Makros > Makro ...'''
* in OOo 1.9.x und höher unter ''' Extras > Makros > Makros verwalten > OpenOffice.org Basic...'''

Zum Einstieg benutzen wir das "Modul1" aus der Bibliothek "Standard" des aktuellen Benutzers:

Geben Sie einen Namen für das neue Makro ein: "HelloWorld"

Wählen Sie die Option '''Standard''' im Auswahlfeld "Makro aus:"

Klicken Sie auf '''Neu'''

Jetzt sollten Sie etwa folgendes sehen:

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub

Sub HelloWorld

End Sub
</code>

Der Cursor sollte am Anfang der Zeile <tt>Sub HelloWorld</tt> stehen.

{| border="1"
|'''Achtung:'''
|Das geöffnete IDE-Fenster ist sowohl über das Menü im OpenOffice.org-Fenster als auch über die Programmleiste des Betriebssystems erreichbar.
|}

= Eingeben von Programm-Code =

Löschen Sie folgende Zeilen:

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub
</code>

Schreiben Sie unterhalb der Zeile "Sub HelloWorld": <tt>msgbox "Hello World!"</tt>, so dass es in etwa so aussieht:

<code>[oobas]
Sub HelloWorld
msgbox "Hello World!"
End Sub
</code>

{| border="1"
|'''Achtung:'''
|Die IDE beherrscht zwar keine "code completion" (Code-Vervollständigung ???) während der Eingabe, verfügt aber über eine kontext-sensitive Hilfe, wenn Sie während der Eingabe F1 oder "Hilfe" drücken oder der Cursor in einem Befehl steht. Bei OpenOffice.org Basic-Befehlen wird die Groß- und Kleinschreibung nicht unterschieden. So sind die Eingaben msgbox, MSGBOX oder Msgbox äquivalent. Stings (Textvariablen) werden in doppelte Anfürhrungszeichen eingeschlossen.
|-
|}

= Den Code ausführen =

Hierfür gibt es mehrere Möglichkeiten:

* direkt aus der IDE: das Symbol '''Ausführen''' (das 3. Symbol in der 2. Leiste) ruft das ERSTE Makro des aktuellen Moduls auf.
* aus dem Menü "Extras":
** (Version 1.1.x) '''Extras > Makros > Makro…''';
** (Version 1.9.x und höher) '''Extras > Makro > Makro auführen…'''
* Dem Makro ein Tastaturkürzel zuweisen (todo).
* Dem Makro einen Menüeintrag zuweisen (todo).
* Dem Makro ein Symbolleisten-Symbol zuweisen (todo).
* Ein Kontroll-Element in einem Dokument erstellen (todo).
* Das Makro einem Ereignis zuweisen (todo)

Führen Sie für den Anfang die "HelloWorld"-Subroutine aus, indem Sie auf das '''Ausführen'''-Symbol klicken. Ein kleiner Dialog mit dem Titel "soffice" und dem Text "Hello World" sollte aufpoppen.

= Speichern des Code =

Der Code wird immer automatisch gespeichert, wenn sein Container gespeichert wird. Wenn das Modul also in einer (allgemeinen oder benutzerspezifischen) OpenOffice.org-Bibliothek enthalten ist, wird es beim Schließen der Anwendung OpenOffice.org gespeichert. Entsprechend werden Dokument-interne Bibliotheken biem Speichern des Dokuments mit-gesichert.

Auf der Standard-Symbolleiste der IDE (normalerweise die oberste Symbolleiste) finden Sie ein Symbol "Speichern". Befindet sich der Code in einem Dokument oder einer Vorlage, dann speichert der Klick auf dieses Symbol das gesamte Dokument. Handelt es sich dagegen um eine OpenOffice.org-Bibliothek, wird nur die aktuelle Bibliothek gespeichert.

= Variablen =

Bei Variablen kann durch <tt>Option Explicit</tt> zu Beginn des Moduls die explizite Deklaration erzwungen werden. Zu Sinn und Unsinn des Deklarierens von Variablen lesen Sie [http://www.oooforum.org/forum/viewtopic.phtml?t=5845 diese Diskussion].

In dieser Diskussion vertritt der ursprüngliche Autor dieses Wiki-Beitrags die Position, dass Variablen immer deklariert werden sollten. Mittlerweile hat er seine Meinung geändert. Kurz: es ist eine Frage des persönlichen Geschmacks. Unabhängig davon sollten nach Auffassung des ursprünglichen Autors Variablen nach folgener Konvention benannt werden, die auch bei den Beispielen aus diesem Wiki verwendet wurde:

Der erste Buchstabe der Variable steht für den Typ des in der Variable gespeicherten Wertes. Dabei bezeichnen folgende Buchstaben die entsprechenden Datentypen (in Anlehung an das Tutorial.pdf von Sun):

{| border="1"
|'''''Buchstabe'''''
|'''''Bedeutung'''''
|-
|a
|Struktur (Structure)
|-
|b
|Bool'sch (WAHR oder FALSCH)
|-
|e
|Aufzählung (Enumeration). Diese Variable kann nur einen begrenzten Satz von Werten enthalten.
|-
|f
|Fließkomma-Zahl (3.402823 x 1038 bis 1.401298 x 10-45. Eine einzelne Variable kann bis zu 4 Bytes umfassen) "Double" (doppelte Genauigkeit, 1.79769313486232 x 10308 bis 4.94065645841247 x 10-324. Eine Double-Variable kann bis zu 8 Bytes umfassen) Währung (-922337203685477.5808 bis +922337203685477.5807 ebenfalls 8 Byte umfassend)
|-
|m
|Feld (Array) (aka Sequenz aka Matrix)
|-
|n
|Integer (-32768 to 32767.) oder Long (-2147483648 and 2147483647).
|-
|o
|Objekt, Service oder Interface
|-
|s
|Text (String) (Eine String-Variable kann bis zu 65535 Unicode-Zeichen enthalten).
|-
|x
|Schnittstelle (Interface), um anzuzeigen, dass nur Methoden einer bstimmten Schnittstelle eines Objekts verwendet werden.
|-
|v
|Variant, irgend ein Typ
|-
|}

Benutzen Sie lange, beschreibende Variablennamen unter Verwendung von CamelCase (Groß-Klein-Schreibung).

{| border="1"
|'''Achtung:'''
|Bei benutzerdefinierten OpenOffice.org Basic-Variablen spielt die Groß-/Kleinschreibunge keine Rolle. Bei UNO-API-Konstanten aber sehr wohl!
|}

Ausnahmen von der Regel, lange Namen zu verwenden, sind Index-Variablen (meist i, j oder k), sowie Strings (meist als s bezeichnet).

Bearbeiten Sie nun die sub HelloWorld, so dass der Code ungefähr wie im folgenden aussieht und führen Sie sie aus:

<code>[oobas]
sub HelloWorld
dim i as integer 'This line is optional
for i = 0 to 2
'These lines are indented for ease of reading only
'all your code should be like this for lonog time survival
msgbox "Hello World " & i
next i
end sub
</code>

Mehr Infos zur Verwendung von Variablen erhalten Sie in der Online-Hilfe unter "Variablen benutzen" (???)

= Die OpenOffice.org API =

Dieser Abschnitt beginnt mit einem Beispiel. Anschließend wird das Beispiel erläutert.

Versuchen Sie den folgenden Code in Dokumenten unterschiedlichen Typs auszuführen:

<code>[oobas]
sub main
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
msgbox fnWhichComponent(thisComponent)
end sub

function fnWhichComponent(oDoc) as string
if HasUnoInterfaces(oDoc, "com.sun.star.lang.XServiceInfo") then
if thisComponent.supportsService ("com.sun.star.text.GenericTextDocument") then
fnWhichComponent = "Text"
elseif thisComponent.supportsService("com.sun.star.sheet.SpreadsheetDocument") then
fnWhichComponent = "Spreadsheet"
elseif thisComponent.supportsService("com.sun.star.presentation.PresentationDocument") then
fnWhichComponent = "Presentation"
elseif thisComponent.supportsService("com.sun.star.drawing.GenericDrawingDocument") then
fnWhichComponent = "Drawing"
else
fnWhichComponent = "Oops current document something else"
end if
else
fnWhichComponent = "Not a document"
end if
End function
</code>

== Namenskonventionen für Subroutinen ==
im obigen Beispiel beginnt die Benutzer-definierte Funktion mit den Buchstaben "fn". Diese Konvention (an die sich der ursprüngliche Autor hält) kennzeichnet eine Funktion als Benutzer-definiert. Entsprechend beginnt eine Benutzer-definierte Subroutine mit "sub". Diese im Folgenden benutzten Konventionen sollen Ihnen als Anfängern helfen, Benutzer-definierte von eingebauten Routinen/Funktionen zu unterscheiden.

== Einführung in die OpenOffice.org API ==

In diesem Abschnitt werden folgende Begriffe erläutert:

* Interface (Schnittstelle)
* Modul
* Service (Dienst)
* Methode
* Property (Eigenschaft)

Den Unterschied zwischen einer Schnittstelle und einem Service zu kennen, ist zwar nicht unbedingt Voraussetzung zum Programmieren unter OpenOffice.org, aber es hilft, die Dokumentation zu verstehen, und auch bei der Introspektion. Möglicherweise werden Sie den folgenden Abschnitt mindestens zwei mal lesen müssen!

Eine Schnittstelle ist eine ''Definition'' eines Satzes von Methoden (und ihren Argumenten), die ein Dienst, der diese Schnittstelle implementiert, enthalten muss.

Schnittstellen werden aus Gründen der Namensgebung zu '''Modulen''' gruppiert. Alle Schnittstellen (und Dienste) beginnen mit <tt>com.sun.star</tt>, gefolgt vom Modul-Namen, dann kommt der Name der Schnittstelle (oder des Dienstes).

Beispielsweise bieten die meisten Dienste die Schnittstelle <tt>com.sun.star.beans.XPropertySet</tt>. Diese Schnittstelle ist im Modul <tt>beans</tt> gespeichert und ermöglicht Zugriff auf die Eigenschaften (Properties) eines Dienstes. Eine '''Eigenschaft''' ist ein Wert, eine '''Methode''' ist dagegen eine Aktion.

Ein OpenOffice.org-Objekt kann viele Dienste enthalten.

Ein OpenOffice.org-Objekt kann einen Dienst enthalten, der eine Schnittstelle implementiert, in welcher eine Methode beschreibt, dass ein anderes OpenOffice.org-Objekt zurückgegeben wird.

== Introspektion ==

'''HasUnoInterfaces''' ist eine OpenOffice.org-Basic-Funktion zur Introspektion. Informieren Sie sich über [http://www.oooforum.org/forum/viewtopic.phtml?t=7068 Introspektion in anderen Sprachen].

<tt>HasUnoInterfaces</tt> gibt <code>true</code> zurück, wenn beim spezifizierten Objekt alle spezifizierten Schnittstellen verfügbar sind.

Die meisten OpenOffice.org-Objekte enthalten die Methode '''supportsService''' weil sie die Schnittstelle <code>com.sun.star.lang.XServiceInfo</code> enthalten.

Im obigen Beispiel prüft <tt>HasUnoInterfaces</tt>, ob das aktuelle Dokument die Schnittstelle <tt>com.sun.star.lang.XServiceInfo</tt> implementiert, da andernfalls die Methode <tt>supportsService</tt> fehlen würde. Der Aufruf dieser Methode würde in diesem Fall einen Laufzeitfehler verursachen.

<tt>supportsService</tt> ist eine Methode, die den Wert <code>true</code> zurückgibt, wenn der spezifizierte Service verfügbar ist. Das obige Beispiel prüft das Vorhandensein eines Service, um so den Typ des aktuell aktiven Dokuments zu bestimmen.

== X-Ray tool ==
Die Benutzung von <tt>HasUnoInterfaces</tt> und <tt>supportsService</tt> reicht aus, um sich zur Laufzeit über ein Objekt zu informieren, aber zum Lernen eignet sich das [http://ooomacros.org/dev.php#101416 X-Ray tool von Bernard Marcelly] viel besser. Laden Sie das ZIP-File herunter, entpacken Sie es und öffnen Sie das enthaltene Dokument mit OpenOffice.org. Befolgen Sie anschließend die Installationsanweisungen.

Das '''X-Ray tool''' verlangt bei der Konfiguration eine lokale Kopie des OpenOffice.org SDK. Laden Sie es von ??? herunter und entpacken Sie es.

Nun können Sie die beiden auskommentierten Zeilen des obigen Beispiels entkommentieren (den Apostroph entfernen):

<code>[oobas]
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
</code>

Führen Sie das Makro dann erneut aus.

Ab Xray Version 5 heißt das Kommando einfach '''xray'''.

'''BasicLibraries''' ist ein OpenOffice.org-Basic-Befehl, der ein Objekt zurückgibt, mit dem man auf die OpenOffice.org Bibliotheken zugreifen kann. Die Methode <tt>loadLibrary</tt> macht die Routinen aus dieser Bibliothek verfügbar.

<tt>xray.xray</tt> spezifiziert die Subroutine <tt>xray</tt> im Modul <tt>xray</tt> in dieser Bibliothek, <tt>thisComponent</tt> ist das Objekt, das an xray zur Introspektion übergeben wird.

Um mit einem bestimmten Objekt zu arbeiten erfordert häufig, dieses Objekt zu finden oder zu erzeugen, indem man mit <tt>StarDesktop</tt> oder <tt>thisComponent</tt> beginnt.

== Desktop, Dokumente, Selektionen ==
<tt>StarDesktop</tt> und <tt>ThisComponent</tt> sind OpenOffice.org-Basic-Befehle, die sich auf die Applikation bzw. das aktuell aktive Dokument beziehen.

Im Unterschied zu Microsoft Office ist OpenOffice.org eine Anwendung mit unterschiedlichen Komponenten. Beim Ausführen von Code möchte man häufig wissen, welche Komponente aktuell aktiv ist. Der obige Code zeigt eine Möglichkeit, dies zu überprüfen.

StarDesktop bezieht sich auf einen konzeptuellen Desktop (der historisch tatsächlich mal existiert hat) und meint de facto die Anwendung OpenOffice.org.

== Neue Dokumente erzeugen ==
Um ein neues Text-Dokument zu erzeugen:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/swriter", "_blank", 0, Array())
</code>
Um ein neues Tabellen-Dokument zu erzeugen:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/scalc", "_blank", 0, Array())
</code>
Ein sinnvoller Ansatz wäre, eine einfache Funktion zu schreiben:

<code>[oobas]
function fnNewDoc(sDocType as string)
fnNewDoc = StarDesktop.loadComponentFromURL("private:factory/" & sDocType , "_blank", 0, Array())
end function
</code>
Dann könnte man neue Dokumente ganz einfach erzeugen:

<code>[oobas]
oDoc = fnNewDoc("swriter")
oDoc = fnNewDoc("scalc")
oDoc = fnNewDoc("simpress")
oDoc = fnNewDoc("sdraw")
oDoc = fnNewDoc("smath")
</code>
Siehe http://api.openoffice.org/docs/common/ref/com/sun/star/frame/XComponentLoader.html .

== Ein bestehendes Dokument öffnen ==
Im folgenden Beispiel sehen Sie, wie Sie eine Datei öffnen können. OpenOffice.org URLs sind in [[DE: URL Grundlagen]] erläutert.

<code>[oobas]
sFile = "C:\Documents and Settings\danny\Desktop\MyCalc.sxc" ' Windows
sFile = "/home/danny/Desktop/MyCalc.sxc" ' Linux
sURL = ConvertToURL(sFile)
oDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
</code>
Auch hier könnte eine einfache Funktion das Schreiben verkürzen:

<code>[oobas]
function fnOpenDoc(sFile)
sURL = ConvertToURL(sFile)
fnOpenDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
end function
</code>
Beispiele für Aufrufe:

<code>[oobas]
oDoc = fnOpenDoc("C:\Documents and Settings\danny\Desktop\MyCalc.sxc") ' Windows
oDoc = fnOpenDoc("/home/danny/Desktop/MyCalc.sxc") ' Linux
</code>

== Die aktuelle Selektion ==
Häufig werden Sie eine Funktion schreiben wollen, die etwas mit dem aktuell selektierten Bereich anstellt. <tt>ThisComponent</tt> enthält die Methode <tt>getCurrentSelection</tt>. Da viele unterschiedliche Objekte selektiert sein könnten, werden Sie zuerst prüfen wollen, ob das selektierte Objekt über den Dienst verfügt, der die Methode enthält, mit der Sie das Objekt bearbeiten wollen.

Editieren Sie die Subroutine main im nachfolgenden Code und führen Sie sie mehrfach in einem Textdokument aus, wobei Sie unterschiedliche Objekte selektieren. (Um mehr als einen Textblock zu selektieren, betätigen Sie die '''Strg'''-Taste).

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
'xray.xray oCurSelection
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
msgbox "There are " & oCurSelection.getCount() & _
" selections in the current text document."
end if
end if
end sub
</code>
Wenn nichts selektiert ist, beträgt die Anzahl der Selektionen eins (nämlich der Einfügepunkt), wenn ein Textblock selektiert ist, beträgt die Anzahl ebenfalls eins, wenn zwei Textblöcke selektiert sind, beträgt sie drei: der Einfügepunkt sowie die beiden selektierten Textblöcke.

Übung 1: Modifizieren Sie den obigen Code so, dass er mit selektierten Zellbereichen in einem Tabellendokument funktioniert.

Frage 1: Wie hoch ist die Anzahl der Selektionen, wenn zwei Zellblöcke selektiert sind?

==Properties==
Wenn Sie die Zeile <tt>'xray.xray oCurSelection</tt> entkommentieren, so dass xray läuft, sehen Sie, dass das Objekt, worauf <tt>oCurSelection</tt> zeigt, eine "Property" namens <tt>Count</tt> besitzt, mit einer Beschreibung "pseudo-prop, read only". In OpenOffice.org Basic könnten Sie <tt>oCurSelection.count</tt> schreiben, da dies aber in keiner anderen Sprache, mit der Sie auf die OpenOffice.org API zugreifen können, möglich ist, werde ich versuchen, in diesem Wiki nur über Methoden zuzugreifen. (Möglicherweise vergesse ich das auch das eine oder andere Mal).

Das nächste Beispiel zeigt, wie man einen Property-Wert für die aktuellen Selektionen ändert.

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
nCount = oCurSelection.Count
'xray.xray oCurSelection.getByIndex(0)
'Warnung: Am Einfügepunkt wird die selbe Aktion zwei mal angewandt -
'das macht in diesem Fall nichts, kann aber durchaus problematisch werden.
for i = 0 to nCount - 1
oCurSelection.getByIndex(i).setPropertyValue("CharStyleName", "Strong Emphasis")
next
end if
end if
end sub
</code>

In OpenOffice.org Basic kann man die Zuweisung auch abkürzen:

<code>[oobas]
oCurSelection(i).CharStyleName = "Strong Emphasis"
</code>
Hier in diesem Wiki versuche ich, sowohl zur Indexierung als auch zur Zuweisung von Properties die vollständigen Methoden zu verwenden. Dadurch kann der Code leichter in andere Sprachen portiert werden und es hilft Ihnen auch, zu verstehen, was vor sich geht (nochmal: Bitte um Entschuldigung, wenn ich mal von dieser Regel abweiche, weil ich es eigentlich nicht gewohnt bin)

Übung 2: Schreiben Sie den obigen Code so um, dass die Warnung entfernt werden kann.

Siehe [[DE:Aktuelle Selektion]] ([[ Current selection]]).

=Iterative Access to Subordinate Objects (Enumeration access)=
Sometimes to access the desired object an enumeration is required. For example paragraphs, within a document or within a selection.

When a Writer document is active and some text is selected, both <tt>thisDocument.getText()</tt> and <tt>thisComponent.getCurrentSelection().getByIndex(i)</tt> have the service: com.sun.star.text.TextRange which has the interface: com.sun.star.container.XContentEnumerationAccess, it is possible to create an enumeration of the paragraphs for the current document or for a particular selection.

<code>[oobas]
' Create enumeration object
oTextElementEnum = thisComponent.getText().createEnumeration()
'or thisComponent.getCurrentSelection().getByIndex(i).createEnumeration()

' loop over all text elements
while oTextElementEnum.hasMoreElements()
oTextElement = oTextElementEnum.nextElement
if oTextElement.supportsService("com.sun.star.text.TextTable") then
MsgBox "The current block contains a table."
end if
if oTextElement.supportsService("com.sun.star.text.Paragraph") then
MsgBox "The current block contains a paragraph."
end if
wend
</code>
Exercise 3: Extend the above example to display in a message box all text portions that are bold.

=Named access=
Some objects provide named access to a particular type of subordinate object, some others indexed access, and some both named and indexed access.

For example if the current document in OpenOffice.org is a spreadsheet then to access a particular sheet can be done by index access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByIndex(0)
</code>
or named access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByName("Sheet1")
</code>
To check if an object with a particular name already exists use <tt>hasByName</tt>, for example:

<code>[oobas]
if thisComponent.getSheets.hasByName("Sheet1") then
</code>
To loop through all the available object names can be done like:

<code>[oobas]
mNames = thisComponent.getSheets.getElementnames
for i = lbound(mNames) to ubound(mNames)
msgbox mNames(i)
next
</code>

Some named subordinate objects also provide the interface: com.sun.star.container.XNameContainer. This interface defines that such objects should have the following methods: <tt>insertByName</tt>, <tt>replaceByname</tt> and <tt>removeByName</tt>.

E.g.

<code>[oobas]
thisComponent.getSheets.insertByName("NewSheet")
</code>

=Create new objects=
Some objects have services which implement interfaces to provide specific methods for creating a particular type of object.

For example if the current document is a Writer document then <tt>thisComponent.getText</tt> is an object that provides the service com.sun.star.text.Text which implements the interface com.sun.star.text.XSimpleText which defines the methods <tt>createTextCursor</tt> and <tt>createTextCursorByRange</tt>. Both of these methods create a text cursor for accessing the text of the document. These cursors are quite independent of the view cursor . The view cursor is visible on the screen and is manipulated by the user (and can be manipulated by program control), where as a text cursor is not visible on the screen and is solely used by program control. The following code snippet demonstrates creating a new text cursor, such that it starts at the same location as the viewCursor and is then moved independent of the view cursor.

<code>[oobas]
oVC = thisComponent.getCurrentController.getViewCursor
oCursor = oVC.getText.createTextCursorByRange(oVC)
oCursor.gotoStartOfSentence(false)
oCursor.gotoEndOfSentence(true)
msgbox oCursor.getString
</code>

Some objects are context dependent and get created using the method <tt>createInstance</tt> which is defined in the interface com.sun.star.lang.XMultiServiceFactory. For example to add a rectangle to the first page of a drawing document:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
dim aSize as new com.sun.star.awt.Size

aPoint.x = 1000
aPoint.y = 1000

aSize.Width = 10000
aSize.Height = 10000

oRectangleShape = thisComponent.createInstance("com.sun.star.drawing.RectangleShape")
oRectangleShape.Size = aSize
oRectangleShape.Position = aPoint

thisComponent.getDrawPages.getByIndex(0).add(oRectangleShape)
</code>

This example also uses UNO structs see below for more information on UNO stucts.

Some objects are context independent to create these objects use the OpenOffice.org Basic command createUnoService. For example to create the equivalent to StarDesktop:

<code>[oobas]
oDesktop = createUnoService("com.sun.star.frame.Desktop")
</code>

The process that I use to determine how to access or create an object is as follows:

Does the object already exist if so I should be able to access it from something like <tt>thisComponent</tt>.

Will the new object belong to another object, if so does the owner have a specific method for creating the object, if so use it.

The new object will belong to another object, but that object doesn't provide a specific method for creating it, but does provide <tt>createInstance</tt>. If the object doesn't provide <tt>createInstance</tt> are you sure you are using the correct object, or is it context independent.

I have found working out how to create an object to be quite difficult with existing documentation so I hope that this document/wiki will eventually make this clear.

==UNO structs==
UNO structures can be declared using the OpenOffice.org Basic command <tt>dim</tt>:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
</code>
Or by using the OpenOffice.org Basic command <tt>createUnoStruct</tt>:

<code>[oobas]
aPoint = createUnoStruct("com.sun.star.awt.Point")
</code>

{| border="1"
|'''Note:'''
|When declaring UNO structs case is important. Note that everything upto the name of the struct is lowercase, and that the name of the struct is in TitleCase.
|}

==Creating Listeners and Handlers==
Through the user interface it is possible to assign macros to some events:

OpenOffice.org versions 1.1.x: '''Tools > Configure… > Events'''.

OpenOffice.org versions 1.9.x and above: '''Tools > Customize… > Events'''.

It is also possible to assign macros to a wider range of events using the OpenOffice.org Basic command CreateUnoListener. This same command is used for creating both listeners and handlers. A listener checks for an event and always allows other listeners to respond to the event as well. A handler listens for an event, and can optionally consume the event so that other listeners don't get to act on it.

The following example creates a keyHandler:

<code>[oobas]
global IannzExampleKeyHandler

sub SetupKeyHandler
oController = thisComponent.currentController
IannzExampleKeyHandler = CreateUnoListener("KeyHandler_","com.sun.star.awt.XKeyHandler")
oController.addKeyHandler(IannzExampleKeyHandler) ' Register the listener
end sub

sub RemoveKeyHandler
thisComponent.currentController.removeKeyHandler(IannzExampleKeyHandler)
end sub

sub KeyHandler_disposing
end sub

function KeyHandler_keyReleased(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyReleased = False
end function

function KeyHandler_keyPressed(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyPressed = false 'Let other listeners handle the event
if oKeyEvent.modifiers = com.sun.star.awt.KeyModifier.MOD2 then 'Control key was pressed
if oKeyEvent.keyCode = com.sun.star.awt.Key.Q then
msgbox "Alt + Q was pressed"
KeyHandler_keyPressed = true 'Don't let other listeners process this event
end if
end if
end function
</code>
A variable declared as global keeps its value even after the macro exits. In this case we want to be able to use this variable later to remove the handler. As variables declared globally could be used in other libraries to try and avoid conflict I start all my global variables with Iannz my registered name for the OpenOffice.org web site.

<tt>sub SetupKeyHandler</tt> sets up the handler. The first parameter to CreateUnoListener is the staring name for the methods that will be called when that type of event occurs in this example .<tt>"KeyHandler_"</tt>.

The second parameter is the name of the interface for the listener or handler, "com.sun.star.awt.XKeyHandler". The name is case sensitive, everything up to and including the module name is always lowercase, the name of the interface always starts with "X" and the remainder is in TitleCase.

Use the SDK to find out what methods the interface must supply. You must supply routines for all of these methods even if you don't intend to use them. You also need to supply a disposing method. The names of these routines start with the string given in the first parameter to CreateUnoListener , in this example <tt>"KeyHandler_"</tt>.

Thus in the example there is <tt>KeyHandler_disposing</tt> and <tt>KeyHandler_keyReleased</tt> which don't actually do anything but are required, and <tt>KeyHandler_keyPressed</tt> which actually does the job.

<tt>sub RemoveKeyHandler</tt> demonstrates how to remove the handler.

=OpenOffice.org constants=
The above example uses OpenOffice.org constants.

E.g. com.sun.star.awt.KeyModifier.MOD2

OpenOffice.org constants are case sensitive. Everything up to and including the module name is always lowercase. The constant group is in TitleCase. The actual constant name is always UPPERCASE.

Programmers not using OpenOffice.org Basic may not have access to these constants.

=Using the recorder=
See [[ The OpenOffice.org recorder and UNO dispatch calls]] section for a discussion on recording UNO Dispatch commands versus writing API calls.

[[Category:Basic:Tutorials]]

DE/Makro Basic Tutorial

2006-09-06T00:56:44Z

Global667: /* Wohin schreibe ich den Code? */

[[Category:de.openoffice.org|Makro Basic Tutorial]]

{| cellspacing=0 cellpadding=5 style="border: 1px solid black;"
| bgcolor=orange colspan=2 |'''Achtung, work in progress'''
Dieses Dokument wird gerade übersetzt, wer mag, darf auch gerne helfen.
|-
|'''Arbeitstitel:''' || "Einführung: Basic für OOo-Erweiterungen"
|-
|'''Originaldokument:''' || [[Extensions_development_basic]] 
|-
|'''Ursprünglicher Autor:''' || Ian Laurenson
|-
| offene Fragen: || sind mit ??? gekennzeichnet
|}

Diese Seite soll Ihnen eine Einführung in das Schreiben von Makros mit OpenOffice.org Basic geben. Grundkenntnisse im Programmieren werden vorausgesetzt. Bitte fühlen Sie sich frei, diese Seite zu editieren, um sie lesbarer zu machen. Ich hoffe, das Sie Ihnen von Nutzen sein wird.

Wenn Sie bereits mit den Grundlagen vertraut sind, können Sie sich auch direkt im KochBuch ([[CookBook]]) Wrapper (Hüllfunktionen ???) und Beispiele anschauen.

= Wohin schreibe ich den Code? =

Der Basic-Code wird bei OpenOffice.org in '''Modulen''' gespeichert, die in '''Bibliotheken''' zusammengefasst sind.

Eine Bibliothek kann
* '''allgemein''', also für die gesamte (Netzwerk-) Installation verfügbar sein ("OOo Makros und Dialoge")
* nur für den aktuellen '''Benutzer''' verfügbar sein ("Meine Makros und Dialoge")
* in einem '''Dokument''' oder in einer Vorlage abgelegt sein, so dass ihr Code nur zur Verfügung steht, wenn das Dokument geöffnet ist.
Bibliotheken, die nicht in einem Dokument abgelegt sind (also allgemein oder für den aktuellen Benutzer verfügbare Bibliotheken) werden im Folgenden als ''OpenOffice.org Bibliotheken'' zusammengefasst.

Der physische Speicherort für diese OpenOffice.org Bibliotheken wird unter '''Extras > Optionen… > OpenOffice.org > Pfade > BASIC''' festgelegt.

{| border="1"
|'''Anmerkung:'''
|Hüten Sie sich, Bibliotheken auf Dateisystem-Ebene zu verschieben oder zu kopieren. Benutzen Sie stattdessen den Dialog "Makros verwalten" oder den Paket-Manager
|}

Module in Biblitheken können maximal 64kb groß sein. Eine Bibliothek cann bis zu 16 000 Module enthalten. Weitere Infos finden Sie in der Online-Hilfe unter "Module und Bibliotheken" (???).

= Die Entwicklungsumgebung (IDE) =

Öffnen Sie die Entwicklungsumgebung:
* in OOo 1.1.x unter '''Extras > Makros > Makro ...'''
* in OOo 1.9.x und höher unter ''' Extras > Makros > Makros verwalten > OpenOffice.org Basic...'''

Zum Einstieg benutzen wir das "Modul1" aus der Bibliothek "Standard" des aktuellen Benutzers:

Geben Sie einen Namen für das neue Makro ein: "HelloWorld"

Wählen Sie die Option '''Standard''' im Auswahlfeld "Makro aus:"

Klicken Sie auf '''Neu'''

Jetzt sollten Sie etwa folgendes sehen:

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub

Sub HelloWorld

End Sub
</code>

Der Cursor sollte am Anfang der Zeile <tt>Sub HelloWorld</tt> stehen.

{| border="1"
|'''Achtung:'''
|Das geöffnete IDE-Fenster ist sowohl über das Menü im OpenOffice.org-Fenster als auch über die Programmleiste des Betriebssystems erreichbar.
|}

= Eingeben von Programm-Code =

Löschen Sie folgende Zeilen:

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub
</code>

Schreiben Sie unterhalb der Zeile "Sub HelloWorld": <tt>msgbox "Hello World!"</tt>, so dass es in etwa so aussieht:

<code>[oobas]
Sub HelloWorld
msgbox "Hello World!"
End Sub
</code>

{| border="1"
|'''Achtung:'''
|Die IDE beherrscht zwar keine "code completion" (Code-Vervollständigung ???) während der Eingabe, verfügt aber über eine kontext-sensitive Hilfe, wenn Sie während der Eingabe F1 oder "Hilfe" drücken oder der Cursor in einem Befehl steht. Bei OpenOffice.org Basic-Befehlen wird die Groß- und Kleinschreibung nicht unterschieden. So sind die Eingaben msgbox, MSGBOX oder Msgbox äquivalent. Stings (Textvariablen) werden in doppelte Anfürhrungszeichen eingeschlossen.
|-
|}

= Den Code ausführen =

Hierfür gibt es mehrere Möglichkeiten:

* direkt aus der IDE: das Symbol '''Ausführen''' (das 3. Symbol in der 2. Leiste) ruft das ERSTE Makro des aktuellen Moduls auf.
* aus dem Menü "Extras":
** (Version 1.1.x) '''Extras > Makros > Makro…''';
** (Version 1.9.x und höher) '''Extras > Makro > Makro auführen…'''
* Dem Makro ein Tastaturkürzel zuweisen (todo).
* Dem Makro einen Menüeintrag zuweisen (todo).
* Dem Makro ein Symbolleisten-Symbol zuweisen (todo).
* Ein Kontroll-Element in einem Dokument erstellen (todo).
* Das Makro einem Ereignis zuweisen (todo)

Führen Sie für den Anfang die "HelloWorld"-Subroutine aus, indem Sie auf das '''Ausführen'''-Symbol klicken. Ein kleiner Dialog mit dem Titel "soffice" und dem Text "Hello World" sollte aufpoppen.

= Speichern des Code =

Der Code wird immer automatisch gespeichert, wenn sein Container gespeichert wird. Wenn das Modul also in einer (allgemeinen oder benutzerspezifischen) OpenOffice.org-Bibliothek enthalten ist, wird es beim Schließen der Anwendung OpenOffice.org gespeichert. Entsprechend werden Dokument-interne Bibliotheken biem Speichern des Dokuments mit-gesichert.

Auf der Standard-Symbolleiste der IDE (normalerweise die oberste Symbolleiste) finden Sie ein Symbol "Speichern". Befindet sich der Code in einem Dokument oder einer Vorlage, dann speichert der Klick auf dieses Symbol das gesamte Dokument. Handelt es sich dagegen um eine OpenOffice.org-Bibliothek, wird nur die aktuelle Bibliothek gespeichert.

= Variablen =

Bei Variablen kann durch <tt>Option Explicit</tt> zu Beginn des Moduls die explizite Deklaration erzwungen werden. Zu Sinn und Unsinn des Deklarierens von Variablen lesen Sie [http://www.oooforum.org/forum/viewtopic.phtml?t=5845 diese Diskussion].

In dieser Diskussion vertritt der ursprüngliche Autor dieses Wiki-Beitrags die Position, dass Variablen immer deklariert werden sollten. Mittlerweile hat er seine Meinung geändert. Kurz: es ist eine Frage des persönlichen Geschmacks. Unabhängig davon sollten nach Auffassung des ursprünglichen Autors Variablen nach folgener Konvention benannt werden, die auch bei den Beispielen aus diesem Wiki verwendet wurde:

Der erste Buchstabe der Variable steht für den Typ des in der Variable gespeicherten Wertes. Dabei bezeichnen folgende Buchstaben die entsprechenden Datentypen (in Anlehung an das Tutorial.pdf von Sun):

{| border="1"
|'''''Buchstabe'''''
|'''''Bedeutung'''''
|-
|a
|Struktur (Structure)
|-
|b
|Bool'sch (WAHR oder FALSCH)
|-
|e
|Aufzählung (Enumeration). Diese Variable kann nur einen begrenzten Satz von Werten enthalten.
|-
|f
|Fließkomma-Zahl (3.402823 x 1038 bis 1.401298 x 10-45. Eine einzelne Variable kann bis zu 4 Bytes umfassen) "Double" (doppelte Genauigkeit, 1.79769313486232 x 10308 bis 4.94065645841247 x 10-324. Eine Double-Variable kann bis zu 8 Bytes umfassen) Währung (-922337203685477.5808 bis +922337203685477.5807 ebenfalls 8 Byte umfassend)
|-
|m
|Feld (Array) (aka Sequenz aka Matrix)
|-
|n
|Integer (-32768 to 32767.) oder Long (-2147483648 and 2147483647).
|-
|o
|Objekt, Service oder Interface
|-
|s
|Text (String) (Eine String-Variable kann bis zu 65535 Unicode-Zeichen enthalten).
|-
|x
|Schnittstelle (Interface), um anzuzeigen, dass nur Methoden einer bstimmten Schnittstelle eines Objekts verwendet werden.
|-
|v
|Variant, irgend ein Typ
|-
|}

Benutzen Sie lange, beschreibende Variablennamen unter Verwendung von CamelCase (Groß-Klein-Schreibung).

{| border="1"
|'''Achtung:'''
|Bei benutzerdefinierten OpenOffice.org Basic-Variablen spielt die Groß-/Kleinschreibunge keine Rolle. Bei UNO-API-Konstanten aber sehr wohl!
|}

Ausnahmen von der Regel, lange Namen zu verwenden, sind Index-Variablen (meist i, j oder k), sowie Strings (meist als s bezeichnet).

Bearbeiten Sie nun die sub HelloWorld, so dass der Code ungefähr wie im folgenden aussieht und führen Sie sie aus:

<code>[oobas]
sub HelloWorld
dim i as integer 'This line is optional
for i = 0 to 2
'These lines are indented for ease of reading only
'all your code should be like this for lonog time survival
msgbox "Hello World " & i
next i
end sub
</code>

Mehr Infos zur Verwendung von Variablen erhalten Sie in der Online-Hilfe unter "Variablen benutzen" (???)

= Die OpenOffice.org API =

Dieser Abschnitt beginnt mit einem Beispiel. Anschließend wird das Beispiel erläutert.

Versuchen Sie den folgenden Code in Dokumenten unterschiedlichen Typs auszuführen:

<code>[oobas]
sub main
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
msgbox fnWhichComponent(thisComponent)
end sub

function fnWhichComponent(oDoc) as string
if HasUnoInterfaces(oDoc, "com.sun.star.lang.XServiceInfo") then
if thisComponent.supportsService ("com.sun.star.text.GenericTextDocument") then
fnWhichComponent = "Text"
elseif thisComponent.supportsService("com.sun.star.sheet.SpreadsheetDocument") then
fnWhichComponent = "Spreadsheet"
elseif thisComponent.supportsService("com.sun.star.presentation.PresentationDocument") then
fnWhichComponent = "Presentation"
elseif thisComponent.supportsService("com.sun.star.drawing.GenericDrawingDocument") then
fnWhichComponent = "Drawing"
else
fnWhichComponent = "Oops current document something else"
end if
else
fnWhichComponent = "Not a document"
end if
End function
</code>

== Namenskonventionen für Subroutinen ==
im obigen Beispiel beginnt die Benutzer-definierte Funktion mit den Buchstaben "fn". Diese Konvention (an die sich der ursprüngliche Autor hält) kennzeichnet eine Funktion als Benutzer-definiert. Entsprechend beginnt eine Benutzer-definierte Subroutine mit "sub". Diese im Folgenden benutzten Konventionen sollen Ihnen als Anfängern helfen, Benutzer-definierte von eingebauten Routinen/Funktionen zu unterscheiden.

== Einführung in die OpenOffice.org API ==

In diesem Abschnitt werden folgende Begriffe erläutert:

* Interface (Schnittstelle)
* Modul
* Service (Dienst)
* Methode
* Property (Eigenschaft)

Den Unterschied zwischen einer Schnittstelle und einem Service zu kennen, ist zwar nicht unbedingt Voraussetzung zum Programmieren unter OpenOffice.org, aber es hilft, die Dokumentation zu verstehen, und auch bei der Introspektion. Möglicherweise werden Sie den folgenden Abschnitt mindestens zwei mal lesen müssen!

Eine Schnittstelle ist eine ''Definition'' eines Satzes von Methoden (und ihren Argumenten), die ein Dienst, der diese Schnittstelle implementiert, enthalten muss.

Schnittstellen werden aus Gründen der Namensgebung zu '''Modulen''' gruppiert. Alle Schnittstellen (und Dienste) beginnen mit <tt>com.sun.star</tt>, gefolgt vom Modul-Namen, dann kommt der Name der Schnittstelle (oder des Dienstes).

Beispielsweise bieten die meisten Dienste die Schnittstelle <tt>com.sun.star.beans.XPropertySet</tt>. Diese Schnittstelle ist im Modul <tt>beans</tt> gespeichert und ermöglicht Zugriff auf die Eigenschaften (Properties) eines Dienstes. Eine '''Eigenschaft''' ist ein Wert, eine '''Methode''' ist dagegen eine Aktion.

Ein OpenOffice.org-Objekt kann viele Dienste enthalten.

Ein OpenOffice.org-Objekt kann einen Dienst enthalten, der eine Schnittstelle implementiert, in welcher eine Methode beschreibt, dass ein anderes OpenOffice.org-Objekt zurückgegeben wird.

== Introspektion ==

'''HasUnoInterfaces''' ist eine OpenOffice.org-Basic-Funktion zur Introspektion. Informieren Sie sich über [http://www.oooforum.org/forum/viewtopic.phtml?t=7068 Introspektion in anderen Sprachen].

<tt>HasUnoInterfaces</tt> gibt <code>true</code> zurück, wenn beim spezifizierten Objekt alle spezifizierten Schnittstellen verfügbar sind.

Die meisten OpenOffice.org-Objekte enthalten die Methode '''supportsService''' weil sie die Schnittstelle <code>com.sun.star.lang.XServiceInfo</code> enthalten.

Im obigen Beispiel prüft <tt>HasUnoInterfaces</tt>, ob das aktuelle Dokument die Schnittstelle <tt>com.sun.star.lang.XServiceInfo</tt> implementiert, da andernfalls die Methode <tt>supportsService</tt> fehlen würde. Der Aufruf dieser Methode würde in diesem Fall einen Laufzeitfehler verursachen.

<tt>supportsService</tt> ist eine Methode, die den Wert <code>true</code> zurückgibt, wenn der spezifizierte Service verfügbar ist. Das obige Beispiel prüft das Vorhandensein eines Service, um so den Typ des aktuell aktiven Dokuments zu bestimmen.

== X-Ray tool ==
Die Benutzung von <tt>HasUnoInterfaces</tt> und <tt>supportsService</tt> reicht aus, um sich zur Laufzeit über ein Objekt zu informieren, aber zum Lernen eignet sich das [http://ooomacros.org/dev.php#101416 X-Ray tool von Bernard Marcelly] viel besser. Laden Sie das ZIP-File herunter, entpacken Sie es und öffnen Sie das enthaltene Dokument mit OpenOffice.org. Befolgen Sie anschließend die Installationsanweisungen.

Das '''X-Ray tool''' verlangt bei der Konfiguration eine lokale Kopie des OpenOffice.org SDK. Laden Sie es von ??? herunter und entpacken Sie es.

Nun können Sie die beiden auskommentierten Zeilen des obigen Beispiels entkommentieren (den Apostroph entfernen):

<code>[oobas]
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
</code>

Führen Sie das Makro dann erneut aus.

Ab Xray Version 5 heißt das Kommando einfach '''xray'''.

'''BasicLibraries''' ist ein OpenOffice.org-Basic-Befehl, der ein Objekt zurückgibt, mit dem man auf die OpenOffice.org Bibliotheken zugreifen kann. Die Methode <tt>loadLibrary</tt> macht die Routinen aus dieser Bibliothek verfügbar.

<tt>xray.xray</tt> spezifiziert die Subroutine <tt>xray</tt> im Modul <tt>xray</tt> in dieser Bibliothek, <tt>thisComponent</tt> ist das Objekt, das an xray zur Introspektion übergeben wird.

Um mit einem bestimmten Objekt zu arbeiten erfordert häufig, dieses Objekt zu finden oder zu erzeugen, indem man mit <tt>StarDesktop</tt> oder <tt>thisComponent</tt> beginnt.

== Desktop, Dokumente, Selektionen ==
<tt>StarDesktop</tt> und <tt>ThisComponent</tt> sind OpenOffice.org-Basic-Befehle, die sich auf die Applikation bzw. das aktuell aktive Dokument beziehen.

Im Unterschied zu Microsoft Office ist OpenOffice.org eine Anwendung mit unterschiedlichen Komponenten. Beim Ausführen von Code möchte man häufig wissen, welche Komponente aktuell aktiv ist. Der obige Code zeigt eine Möglichkeit, dies zu überprüfen.

StarDesktop bezieht sich auf einen konzeptuellen Desktop (der historisch tatsächlich mal existiert hat) und meint de facto die Anwendung OpenOffice.org.

== Neue Dokumente erzeugen ==
Um ein neues Text-Dokument zu erzeugen:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/swriter", "_blank", 0, Array())
</code>
Um ein neues Tabellen-Dokument zu erzeugen:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/scalc", "_blank", 0, Array())
</code>
Ein sinnvoller Ansatz wäre, eine einfache Funktion zu schreiben:

<code>[oobas]
function fnNewDoc(sDocType as string)
fnNewDoc = StarDesktop.loadComponentFromURL("private:factory/" & sDocType , "_blank", 0, Array())
end function
</code>
Dann könnte man neue Dokumente ganz einfach erzeugen:

<code>[oobas]
oDoc = fnNewDoc("swriter")
oDoc = fnNewDoc("scalc")
oDoc = fnNewDoc("simpress")
oDoc = fnNewDoc("sdraw")
oDoc = fnNewDoc("smath")
</code>
Siehe http://api.openoffice.org/docs/common/ref/com/sun/star/frame/XComponentLoader.html .

== Ein bestehendes Dokument öffnen ==
Im folgenden Beispiel sehen Sie, wie Sie eine Datei öffnen können. OpenOffice.org URLs sind in [[DE: URL Grundlagen]] erläutert.

<code>[oobas]
sFile = "C:\Documents and Settings\danny\Desktop\MyCalc.sxc" ' Windows
sFile = "/home/danny/Desktop/MyCalc.sxc" ' Linux
sURL = ConvertToURL(sFile)
oDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
</code>
Auch hier könnte eine einfache Funktion das Schreiben verkürzen:

<code>[oobas]
function fnOpenDoc(sFile)
sURL = ConvertToURL(sFile)
fnOpenDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
end function
</code>
Beispiele für Aufrufe:

<code>[oobas]
oDoc = fnOpenDoc("C:\Documents and Settings\danny\Desktop\MyCalc.sxc") ' Windows
oDoc = fnOpenDoc("/home/danny/Desktop/MyCalc.sxc") ' Linux
</code>

== Die aktuelle Selektion ==
Häufig werden Sie eine Funktion schreiben wollen, die etwas mit dem aktuell selektierten Bereich anstellt. <tt>ThisComponent</tt> enthält die Methode <tt>getCurrentSelection</tt>. Da viele unterschiedliche Objekte selektiert sein könnten, werden Sie zuerst prüfen wollen, ob das selektierte Objekt über den Dienst verfügt, der die Methode enthält, mit der Sie das Objekt bearbeiten wollen.

Editieren Sie die Subroutine main im nachfolgenden Code und führen Sie sie mehrfach in einem Textdokument aus, wobei Sie unterschiedliche Objekte selektieren. (Um mehr als einen Textblock zu selektieren, betätigen Sie die '''Strg'''-Taste).

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
'xray.xray oCurSelection
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
msgbox "There are " & oCurSelection.getCount() & _
" selections in the current text document."
end if
end if
end sub
</code>
Wenn nichts selektiert ist, beträgt die Anzahl der Selektionen eins (nämlich der Einfügepunkt), wenn ein Textblock selektiert ist, beträgt die Anzahl ebenfalls eins, wenn zwei Textblöcke selektiert sind, beträgt sie drei: der Einfügepunkt sowie die beiden selektierten Textblöcke.

Übung 1: Modifizieren Sie den obigen Code so, dass er mit selektierten Zellbereichen in einem Tabellendokument funktioniert.

Frage 1: Wie hoch ist die Anzahl der Selektionen, wenn zwei Zellblöcke selektiert sind?

==Properties==
Wenn Sie die Zeile <tt>'xray.xray oCurSelection</tt> entkommentieren, so dass xray läuft, sehen Sie, dass das Objekt, worauf <tt>oCurSelection</tt> zeigt, eine "Property" namens <tt>Count</tt> besitzt, mit einer Beschreibung "pseudo-prop, read only". In OpenOffice.org Basic könnten Sie <tt>oCurSelection.count</tt> schreiben, da dies aber in keiner anderen Sprache, mit der Sie auf die OpenOffice.org API zugreifen können, möglich ist, werde ich versuchen, in diesem Wiki nur über Methoden zuzugreifen. (Möglicherweise vergesse ich das auch das eine oder andere Mal).

Das nächste Beispiel zeigt, wie man einen Property-Wert für die aktuellen Selektionen ändert.

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
nCount = oCurSelection.Count
'xray.xray oCurSelection.getByIndex(0)
'Warnung: Am Einfügepunkt wird die selbe Aktion zwei mal angewandt -
'das macht in diesem Fall nichts, kann aber durchaus problematisch werden.
for i = 0 to nCount - 1
oCurSelection.getByIndex(i).setPropertyValue("CharStyleName", "Strong Emphasis")
next
end if
end if
end sub
</code>

In OpenOffice.org Basic kann man die Zuweisung auch abkürzen:

<code>[oobas]
oCurSelection(i).CharStyleName = "Strong Emphasis"
</code>
Hier in diesem Wiki versuche ich, sowohl zur Indexierung als auch zur Zuweisung von Properties die vollständigen Methoden zu verwenden. Dadurch kann der Code leichter in andere Sprachen portiert werden und es hilft Ihnen auch, zu verstehen, was vor sich geht (nochmal: Bitte um Entschuldigung, wenn ich mal von dieser Regel abweiche, weil ich es eigentlich nicht gewohnt bin)

Übung 2: Schreiben Sie den obigen Code so um, dass die Warnung entfernt werden kann.

Siehe [[DE:Aktuelle Selektion]] ([[ Current selection]]).

=Iterative Access to Subordinate Objects (Enumeration access)=
Sometimes to access the desired object an enumeration is required. For example paragraphs, within a document or within a selection.

When a Writer document is active and some text is selected, both <tt>thisDocument.getText()</tt> and <tt>thisComponent.getCurrentSelection().getByIndex(i)</tt> have the service: com.sun.star.text.TextRange which has the interface: com.sun.star.container.XContentEnumerationAccess, it is possible to create an enumeration of the paragraphs for the current document or for a particular selection.

<code>[oobas]
' Create enumeration object
oTextElementEnum = thisComponent.getText().createEnumeration()
'or thisComponent.getCurrentSelection().getByIndex(i).createEnumeration()

' loop over all text elements
while oTextElementEnum.hasMoreElements()
oTextElement = oTextElementEnum.nextElement
if oTextElement.supportsService("com.sun.star.text.TextTable") then
MsgBox "The current block contains a table."
end if
if oTextElement.supportsService("com.sun.star.text.Paragraph") then
MsgBox "The current block contains a paragraph."
end if
wend
</code>
Exercise 3: Extend the above example to display in a message box all text portions that are bold.

=Named access=
Some objects provide named access to a particular type of subordinate object, some others indexed access, and some both named and indexed access.

For example if the current document in OpenOffice.org is a spreadsheet then to access a particular sheet can be done by index access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByIndex(0)
</code>
or named access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByName("Sheet1")
</code>
To check if an object with a particular name already exists use <tt>hasByName</tt>, for example:

<code>[oobas]
if thisComponent.getSheets.hasByName("Sheet1") then
</code>
To loop through all the available object names can be done like:

<code>[oobas]
mNames = thisComponent.getSheets.getElementnames
for i = lbound(mNames) to ubound(mNames)
msgbox mNames(i)
next
</code>

Some named subordinate objects also provide the interface: com.sun.star.container.XNameContainer. This interface defines that such objects should have the following methods: <tt>insertByName</tt>, <tt>replaceByname</tt> and <tt>removeByName</tt>.

E.g.

<code>[oobas]
thisComponent.getSheets.insertByName("NewSheet")
</code>

=Create new objects=
Some objects have services which implement interfaces to provide specific methods for creating a particular type of object.

For example if the current document is a Writer document then <tt>thisComponent.getText</tt> is an object that provides the service com.sun.star.text.Text which implements the interface com.sun.star.text.XSimpleText which defines the methods <tt>createTextCursor</tt> and <tt>createTextCursorByRange</tt>. Both of these methods create a text cursor for accessing the text of the document. These cursors are quite independent of the view cursor . The view cursor is visible on the screen and is manipulated by the user (and can be manipulated by program control), where as a text cursor is not visible on the screen and is solely used by program control. The following code snippet demonstrates creating a new text cursor, such that it starts at the same location as the viewCursor and is then moved independent of the view cursor.

<code>[oobas]
oVC = thisComponent.getCurrentController.getViewCursor
oCursor = oVC.getText.createTextCursorByRange(oVC)
oCursor.gotoStartOfSentence(false)
oCursor.gotoEndOfSentence(true)
msgbox oCursor.getString
</code>

Some objects are context dependent and get created using the method <tt>createInstance</tt> which is defined in the interface com.sun.star.lang.XMultiServiceFactory. For example to add a rectangle to the first page of a drawing document:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
dim aSize as new com.sun.star.awt.Size

aPoint.x = 1000
aPoint.y = 1000

aSize.Width = 10000
aSize.Height = 10000

oRectangleShape = thisComponent.createInstance("com.sun.star.drawing.RectangleShape")
oRectangleShape.Size = aSize
oRectangleShape.Position = aPoint

thisComponent.getDrawPages.getByIndex(0).add(oRectangleShape)
</code>

This example also uses UNO structs see below for more information on UNO stucts.

Some objects are context independent to create these objects use the OpenOffice.org Basic command createUnoService. For example to create the equivalent to StarDesktop:

<code>[oobas]
oDesktop = createUnoService("com.sun.star.frame.Desktop")
</code>

The process that I use to determine how to access or create an object is as follows:

Does the object already exist if so I should be able to access it from something like <tt>thisComponent</tt>.

Will the new object belong to another object, if so does the owner have a specific method for creating the object, if so use it.

The new object will belong to another object, but that object doesn't provide a specific method for creating it, but does provide <tt>createInstance</tt>. If the object doesn't provide <tt>createInstance</tt> are you sure you are using the correct object, or is it context independent.

I have found working out how to create an object to be quite difficult with existing documentation so I hope that this document/wiki will eventually make this clear.

==UNO structs==
UNO structures can be declared using the OpenOffice.org Basic command <tt>dim</tt>:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
</code>
Or by using the OpenOffice.org Basic command <tt>createUnoStruct</tt>:

<code>[oobas]
aPoint = createUnoStruct("com.sun.star.awt.Point")
</code>

{| border="1"
|'''Note:'''
|When declaring UNO structs case is important. Note that everything upto the name of the struct is lowercase, and that the name of the struct is in TitleCase.
|}

==Creating Listeners and Handlers==
Through the user interface it is possible to assign macros to some events:

OpenOffice.org versions 1.1.x: '''Tools > Configure… > Events'''.

OpenOffice.org versions 1.9.x and above: '''Tools > Customize… > Events'''.

It is also possible to assign macros to a wider range of events using the OpenOffice.org Basic command CreateUnoListener. This same command is used for creating both listeners and handlers. A listener checks for an event and always allows other listeners to respond to the event as well. A handler listens for an event, and can optionally consume the event so that other listeners don't get to act on it.

The following example creates a keyHandler:

<code>[oobas]
global IannzExampleKeyHandler

sub SetupKeyHandler
oController = thisComponent.currentController
IannzExampleKeyHandler = CreateUnoListener("KeyHandler_","com.sun.star.awt.XKeyHandler")
oController.addKeyHandler(IannzExampleKeyHandler) ' Register the listener
end sub

sub RemoveKeyHandler
thisComponent.currentController.removeKeyHandler(IannzExampleKeyHandler)
end sub

sub KeyHandler_disposing
end sub

function KeyHandler_keyReleased(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyReleased = False
end function

function KeyHandler_keyPressed(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyPressed = false 'Let other listeners handle the event
if oKeyEvent.modifiers = com.sun.star.awt.KeyModifier.MOD2 then 'Control key was pressed
if oKeyEvent.keyCode = com.sun.star.awt.Key.Q then
msgbox "Alt + Q was pressed"
KeyHandler_keyPressed = true 'Don't let other listeners process this event
end if
end if
end function
</code>
A variable declared as global keeps its value even after the macro exits. In this case we want to be able to use this variable later to remove the handler. As variables declared globally could be used in other libraries to try and avoid conflict I start all my global variables with Iannz my registered name for the OpenOffice.org web site.

<tt>sub SetupKeyHandler</tt> sets up the handler. The first parameter to CreateUnoListener is the staring name for the methods that will be called when that type of event occurs in this example .<tt>"KeyHandler_"</tt>.

The second parameter is the name of the interface for the listener or handler, "com.sun.star.awt.XKeyHandler". The name is case sensitive, everything up to and including the module name is always lowercase, the name of the interface always starts with "X" and the remainder is in TitleCase.

Use the SDK to find out what methods the interface must supply. You must supply routines for all of these methods even if you don't intend to use them. You also need to supply a disposing method. The names of these routines start with the string given in the first parameter to CreateUnoListener , in this example <tt>"KeyHandler_"</tt>.

Thus in the example there is <tt>KeyHandler_disposing</tt> and <tt>KeyHandler_keyReleased</tt> which don't actually do anything but are required, and <tt>KeyHandler_keyPressed</tt> which actually does the job.

<tt>sub RemoveKeyHandler</tt> demonstrates how to remove the handler.

=OpenOffice.org constants=
The above example uses OpenOffice.org constants.

E.g. com.sun.star.awt.KeyModifier.MOD2

OpenOffice.org constants are case sensitive. Everything up to and including the module name is always lowercase. The constant group is in TitleCase. The actual constant name is always UPPERCASE.

Programmers not using OpenOffice.org Basic may not have access to these constants.

=Using the recorder=
See [[ The OpenOffice.org recorder and UNO dispatch calls]] section for a discussion on recording UNO Dispatch commands versus writing API calls.

[[Category:Basic:Tutorials]]

DE/Makro Basic Tutorial

2006-09-06T00:55:46Z

Global667: /* Wohin schreibe ich den Code? */

[[Category:de.openoffice.org|Makro Basic Tutorial]]

{| cellspacing=0 cellpadding=5 style="border: 1px solid black;"
| bgcolor=orange colspan=2 |'''Achtung, work in progress'''
Dieses Dokument wird gerade übersetzt, wer mag, darf auch gerne helfen.
|-
|'''Arbeitstitel:''' || "Einführung: Basic für OOo-Erweiterungen"
|-
|'''Originaldokument:''' || [[Extensions_development_basic]] 
|-
|'''Ursprünglicher Autor:''' || Ian Laurenson
|-
| offene Fragen: || sind mit ??? gekennzeichnet
|}

Diese Seite soll Ihnen eine Einführung in das Schreiben von Makros mit OpenOffice.org Basic geben. Grundkenntnisse im Programmieren werden vorausgesetzt. Bitte fühlen Sie sich frei, diese Seite zu editieren, um sie lesbarer zu machen. Ich hoffe, das Sie Ihnen von Nutzen sein wird.

Wenn Sie bereits mit den Grundlagen vertraut sind, können Sie sich auch direkt im KochBuch ([[CookBook]]) Wrapper (Hüllfunktionen ???) und Beispiele anschauen.

= Wohin schreibe ich den Code? =

Der Basic-Code wird bei OpenOffice.org in '''Modulen''' gespeichert, die in '''Bibliotheken''' zusammengefasst sind.

Eine Bibliothek kann
* '''allgemein''', also für die gesamte (Netzwerk-) Installation verfügbar sein ("OOo Makros und Dialoge")
* nur für den aktuellen '''Benutzer''' verfügbar sein ("Meine Makros und Dialoge")
* in einem '''Dokument''' oder in einer Vorlage abgelegt sein, so dass ihr Code nur zur Verfügung steht, wenn das Dokument geöffnet ist.
Bibliotheken, die nicht in einem Dokument abgelegt sind (also allgemein oder für den aktuellen Benutzer verfübare Bibliotheken) werden im Folgenden als ''OpenOffice.org Bibliotheken'' zusammengefasst.

Der physische Speicherort für diese OpenOffice.org Bibliotheken wird unter '''Extras > Optionen… > OpenOffice.org > Pfade > BASIC''' festgelegt.

{| border="1"
|'''Anmerkung:'''
|Hüten Sie sich, Bibliotheken auf Dateisystem-Ebene zu verschieben oder zu kopieren. Benutzen Sie stattdessen den Dialog "Makros verwalten" oder den Paket-Manager
|}

Module in Biblitheken können maximal 64kb groß sein. Eine Bibliothek cann bis zu 16 000 Module enthalten. Weitere Infos finden Sie in der Online-Hilfe unter "Module und Bibliotheken" (???).

= Die Entwicklungsumgebung (IDE) =

Öffnen Sie die Entwicklungsumgebung:
* in OOo 1.1.x unter '''Extras > Makros > Makro ...'''
* in OOo 1.9.x und höher unter ''' Extras > Makros > Makros verwalten > OpenOffice.org Basic...'''

Zum Einstieg benutzen wir das "Modul1" aus der Bibliothek "Standard" des aktuellen Benutzers:

Geben Sie einen Namen für das neue Makro ein: "HelloWorld"

Wählen Sie die Option '''Standard''' im Auswahlfeld "Makro aus:"

Klicken Sie auf '''Neu'''

Jetzt sollten Sie etwa folgendes sehen:

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub

Sub HelloWorld

End Sub
</code>

Der Cursor sollte am Anfang der Zeile <tt>Sub HelloWorld</tt> stehen.

{| border="1"
|'''Achtung:'''
|Das geöffnete IDE-Fenster ist sowohl über das Menü im OpenOffice.org-Fenster als auch über die Programmleiste des Betriebssystems erreichbar.
|}

= Eingeben von Programm-Code =

Löschen Sie folgende Zeilen:

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub
</code>

Schreiben Sie unterhalb der Zeile "Sub HelloWorld": <tt>msgbox "Hello World!"</tt>, so dass es in etwa so aussieht:

<code>[oobas]
Sub HelloWorld
msgbox "Hello World!"
End Sub
</code>

{| border="1"
|'''Achtung:'''
|Die IDE beherrscht zwar keine "code completion" (Code-Vervollständigung ???) während der Eingabe, verfügt aber über eine kontext-sensitive Hilfe, wenn Sie während der Eingabe F1 oder "Hilfe" drücken oder der Cursor in einem Befehl steht. Bei OpenOffice.org Basic-Befehlen wird die Groß- und Kleinschreibung nicht unterschieden. So sind die Eingaben msgbox, MSGBOX oder Msgbox äquivalent. Stings (Textvariablen) werden in doppelte Anfürhrungszeichen eingeschlossen.
|-
|}

= Den Code ausführen =

Hierfür gibt es mehrere Möglichkeiten:

* direkt aus der IDE: das Symbol '''Ausführen''' (das 3. Symbol in der 2. Leiste) ruft das ERSTE Makro des aktuellen Moduls auf.
* aus dem Menü "Extras":
** (Version 1.1.x) '''Extras > Makros > Makro…''';
** (Version 1.9.x und höher) '''Extras > Makro > Makro auführen…'''
* Dem Makro ein Tastaturkürzel zuweisen (todo).
* Dem Makro einen Menüeintrag zuweisen (todo).
* Dem Makro ein Symbolleisten-Symbol zuweisen (todo).
* Ein Kontroll-Element in einem Dokument erstellen (todo).
* Das Makro einem Ereignis zuweisen (todo)

Führen Sie für den Anfang die "HelloWorld"-Subroutine aus, indem Sie auf das '''Ausführen'''-Symbol klicken. Ein kleiner Dialog mit dem Titel "soffice" und dem Text "Hello World" sollte aufpoppen.

= Speichern des Code =

Der Code wird immer automatisch gespeichert, wenn sein Container gespeichert wird. Wenn das Modul also in einer (allgemeinen oder benutzerspezifischen) OpenOffice.org-Bibliothek enthalten ist, wird es beim Schließen der Anwendung OpenOffice.org gespeichert. Entsprechend werden Dokument-interne Bibliotheken biem Speichern des Dokuments mit-gesichert.

Auf der Standard-Symbolleiste der IDE (normalerweise die oberste Symbolleiste) finden Sie ein Symbol "Speichern". Befindet sich der Code in einem Dokument oder einer Vorlage, dann speichert der Klick auf dieses Symbol das gesamte Dokument. Handelt es sich dagegen um eine OpenOffice.org-Bibliothek, wird nur die aktuelle Bibliothek gespeichert.

= Variablen =

Bei Variablen kann durch <tt>Option Explicit</tt> zu Beginn des Moduls die explizite Deklaration erzwungen werden. Zu Sinn und Unsinn des Deklarierens von Variablen lesen Sie [http://www.oooforum.org/forum/viewtopic.phtml?t=5845 diese Diskussion].

In dieser Diskussion vertritt der ursprüngliche Autor dieses Wiki-Beitrags die Position, dass Variablen immer deklariert werden sollten. Mittlerweile hat er seine Meinung geändert. Kurz: es ist eine Frage des persönlichen Geschmacks. Unabhängig davon sollten nach Auffassung des ursprünglichen Autors Variablen nach folgener Konvention benannt werden, die auch bei den Beispielen aus diesem Wiki verwendet wurde:

Der erste Buchstabe der Variable steht für den Typ des in der Variable gespeicherten Wertes. Dabei bezeichnen folgende Buchstaben die entsprechenden Datentypen (in Anlehung an das Tutorial.pdf von Sun):

{| border="1"
|'''''Buchstabe'''''
|'''''Bedeutung'''''
|-
|a
|Struktur (Structure)
|-
|b
|Bool'sch (WAHR oder FALSCH)
|-
|e
|Aufzählung (Enumeration). Diese Variable kann nur einen begrenzten Satz von Werten enthalten.
|-
|f
|Fließkomma-Zahl (3.402823 x 1038 bis 1.401298 x 10-45. Eine einzelne Variable kann bis zu 4 Bytes umfassen) "Double" (doppelte Genauigkeit, 1.79769313486232 x 10308 bis 4.94065645841247 x 10-324. Eine Double-Variable kann bis zu 8 Bytes umfassen) Währung (-922337203685477.5808 bis +922337203685477.5807 ebenfalls 8 Byte umfassend)
|-
|m
|Feld (Array) (aka Sequenz aka Matrix)
|-
|n
|Integer (-32768 to 32767.) oder Long (-2147483648 and 2147483647).
|-
|o
|Objekt, Service oder Interface
|-
|s
|Text (String) (Eine String-Variable kann bis zu 65535 Unicode-Zeichen enthalten).
|-
|x
|Schnittstelle (Interface), um anzuzeigen, dass nur Methoden einer bstimmten Schnittstelle eines Objekts verwendet werden.
|-
|v
|Variant, irgend ein Typ
|-
|}

Benutzen Sie lange, beschreibende Variablennamen unter Verwendung von CamelCase (Groß-Klein-Schreibung).

{| border="1"
|'''Achtung:'''
|Bei benutzerdefinierten OpenOffice.org Basic-Variablen spielt die Groß-/Kleinschreibunge keine Rolle. Bei UNO-API-Konstanten aber sehr wohl!
|}

Ausnahmen von der Regel, lange Namen zu verwenden, sind Index-Variablen (meist i, j oder k), sowie Strings (meist als s bezeichnet).

Bearbeiten Sie nun die sub HelloWorld, so dass der Code ungefähr wie im folgenden aussieht und führen Sie sie aus:

<code>[oobas]
sub HelloWorld
dim i as integer 'This line is optional
for i = 0 to 2
'These lines are indented for ease of reading only
'all your code should be like this for lonog time survival
msgbox "Hello World " & i
next i
end sub
</code>

Mehr Infos zur Verwendung von Variablen erhalten Sie in der Online-Hilfe unter "Variablen benutzen" (???)

= Die OpenOffice.org API =

Dieser Abschnitt beginnt mit einem Beispiel. Anschließend wird das Beispiel erläutert.

Versuchen Sie den folgenden Code in Dokumenten unterschiedlichen Typs auszuführen:

<code>[oobas]
sub main
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
msgbox fnWhichComponent(thisComponent)
end sub

function fnWhichComponent(oDoc) as string
if HasUnoInterfaces(oDoc, "com.sun.star.lang.XServiceInfo") then
if thisComponent.supportsService ("com.sun.star.text.GenericTextDocument") then
fnWhichComponent = "Text"
elseif thisComponent.supportsService("com.sun.star.sheet.SpreadsheetDocument") then
fnWhichComponent = "Spreadsheet"
elseif thisComponent.supportsService("com.sun.star.presentation.PresentationDocument") then
fnWhichComponent = "Presentation"
elseif thisComponent.supportsService("com.sun.star.drawing.GenericDrawingDocument") then
fnWhichComponent = "Drawing"
else
fnWhichComponent = "Oops current document something else"
end if
else
fnWhichComponent = "Not a document"
end if
End function
</code>

== Namenskonventionen für Subroutinen ==
im obigen Beispiel beginnt die Benutzer-definierte Funktion mit den Buchstaben "fn". Diese Konvention (an die sich der ursprüngliche Autor hält) kennzeichnet eine Funktion als Benutzer-definiert. Entsprechend beginnt eine Benutzer-definierte Subroutine mit "sub". Diese im Folgenden benutzten Konventionen sollen Ihnen als Anfängern helfen, Benutzer-definierte von eingebauten Routinen/Funktionen zu unterscheiden.

== Einführung in die OpenOffice.org API ==

In diesem Abschnitt werden folgende Begriffe erläutert:

* Interface (Schnittstelle)
* Modul
* Service (Dienst)
* Methode
* Property (Eigenschaft)

Den Unterschied zwischen einer Schnittstelle und einem Service zu kennen, ist zwar nicht unbedingt Voraussetzung zum Programmieren unter OpenOffice.org, aber es hilft, die Dokumentation zu verstehen, und auch bei der Introspektion. Möglicherweise werden Sie den folgenden Abschnitt mindestens zwei mal lesen müssen!

Eine Schnittstelle ist eine ''Definition'' eines Satzes von Methoden (und ihren Argumenten), die ein Dienst, der diese Schnittstelle implementiert, enthalten muss.

Schnittstellen werden aus Gründen der Namensgebung zu '''Modulen''' gruppiert. Alle Schnittstellen (und Dienste) beginnen mit <tt>com.sun.star</tt>, gefolgt vom Modul-Namen, dann kommt der Name der Schnittstelle (oder des Dienstes).

Beispielsweise bieten die meisten Dienste die Schnittstelle <tt>com.sun.star.beans.XPropertySet</tt>. Diese Schnittstelle ist im Modul <tt>beans</tt> gespeichert und ermöglicht Zugriff auf die Eigenschaften (Properties) eines Dienstes. Eine '''Eigenschaft''' ist ein Wert, eine '''Methode''' ist dagegen eine Aktion.

Ein OpenOffice.org-Objekt kann viele Dienste enthalten.

Ein OpenOffice.org-Objekt kann einen Dienst enthalten, der eine Schnittstelle implementiert, in welcher eine Methode beschreibt, dass ein anderes OpenOffice.org-Objekt zurückgegeben wird.

== Introspektion ==

'''HasUnoInterfaces''' ist eine OpenOffice.org-Basic-Funktion zur Introspektion. Informieren Sie sich über [http://www.oooforum.org/forum/viewtopic.phtml?t=7068 Introspektion in anderen Sprachen].

<tt>HasUnoInterfaces</tt> gibt <code>true</code> zurück, wenn beim spezifizierten Objekt alle spezifizierten Schnittstellen verfügbar sind.

Die meisten OpenOffice.org-Objekte enthalten die Methode '''supportsService''' weil sie die Schnittstelle <code>com.sun.star.lang.XServiceInfo</code> enthalten.

Im obigen Beispiel prüft <tt>HasUnoInterfaces</tt>, ob das aktuelle Dokument die Schnittstelle <tt>com.sun.star.lang.XServiceInfo</tt> implementiert, da andernfalls die Methode <tt>supportsService</tt> fehlen würde. Der Aufruf dieser Methode würde in diesem Fall einen Laufzeitfehler verursachen.

<tt>supportsService</tt> ist eine Methode, die den Wert <code>true</code> zurückgibt, wenn der spezifizierte Service verfügbar ist. Das obige Beispiel prüft das Vorhandensein eines Service, um so den Typ des aktuell aktiven Dokuments zu bestimmen.

== X-Ray tool ==
Die Benutzung von <tt>HasUnoInterfaces</tt> und <tt>supportsService</tt> reicht aus, um sich zur Laufzeit über ein Objekt zu informieren, aber zum Lernen eignet sich das [http://ooomacros.org/dev.php#101416 X-Ray tool von Bernard Marcelly] viel besser. Laden Sie das ZIP-File herunter, entpacken Sie es und öffnen Sie das enthaltene Dokument mit OpenOffice.org. Befolgen Sie anschließend die Installationsanweisungen.

Das '''X-Ray tool''' verlangt bei der Konfiguration eine lokale Kopie des OpenOffice.org SDK. Laden Sie es von ??? herunter und entpacken Sie es.

Nun können Sie die beiden auskommentierten Zeilen des obigen Beispiels entkommentieren (den Apostroph entfernen):

<code>[oobas]
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
</code>

Führen Sie das Makro dann erneut aus.

Ab Xray Version 5 heißt das Kommando einfach '''xray'''.

'''BasicLibraries''' ist ein OpenOffice.org-Basic-Befehl, der ein Objekt zurückgibt, mit dem man auf die OpenOffice.org Bibliotheken zugreifen kann. Die Methode <tt>loadLibrary</tt> macht die Routinen aus dieser Bibliothek verfügbar.

<tt>xray.xray</tt> spezifiziert die Subroutine <tt>xray</tt> im Modul <tt>xray</tt> in dieser Bibliothek, <tt>thisComponent</tt> ist das Objekt, das an xray zur Introspektion übergeben wird.

Um mit einem bestimmten Objekt zu arbeiten erfordert häufig, dieses Objekt zu finden oder zu erzeugen, indem man mit <tt>StarDesktop</tt> oder <tt>thisComponent</tt> beginnt.

== Desktop, Dokumente, Selektionen ==
<tt>StarDesktop</tt> und <tt>ThisComponent</tt> sind OpenOffice.org-Basic-Befehle, die sich auf die Applikation bzw. das aktuell aktive Dokument beziehen.

Im Unterschied zu Microsoft Office ist OpenOffice.org eine Anwendung mit unterschiedlichen Komponenten. Beim Ausführen von Code möchte man häufig wissen, welche Komponente aktuell aktiv ist. Der obige Code zeigt eine Möglichkeit, dies zu überprüfen.

StarDesktop bezieht sich auf einen konzeptuellen Desktop (der historisch tatsächlich mal existiert hat) und meint de facto die Anwendung OpenOffice.org.

== Neue Dokumente erzeugen ==
Um ein neues Text-Dokument zu erzeugen:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/swriter", "_blank", 0, Array())
</code>
Um ein neues Tabellen-Dokument zu erzeugen:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/scalc", "_blank", 0, Array())
</code>
Ein sinnvoller Ansatz wäre, eine einfache Funktion zu schreiben:

<code>[oobas]
function fnNewDoc(sDocType as string)
fnNewDoc = StarDesktop.loadComponentFromURL("private:factory/" & sDocType , "_blank", 0, Array())
end function
</code>
Dann könnte man neue Dokumente ganz einfach erzeugen:

<code>[oobas]
oDoc = fnNewDoc("swriter")
oDoc = fnNewDoc("scalc")
oDoc = fnNewDoc("simpress")
oDoc = fnNewDoc("sdraw")
oDoc = fnNewDoc("smath")
</code>
Siehe http://api.openoffice.org/docs/common/ref/com/sun/star/frame/XComponentLoader.html .

== Ein bestehendes Dokument öffnen ==
Im folgenden Beispiel sehen Sie, wie Sie eine Datei öffnen können. OpenOffice.org URLs sind in [[DE: URL Grundlagen]] erläutert.

<code>[oobas]
sFile = "C:\Documents and Settings\danny\Desktop\MyCalc.sxc" ' Windows
sFile = "/home/danny/Desktop/MyCalc.sxc" ' Linux
sURL = ConvertToURL(sFile)
oDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
</code>
Auch hier könnte eine einfache Funktion das Schreiben verkürzen:

<code>[oobas]
function fnOpenDoc(sFile)
sURL = ConvertToURL(sFile)
fnOpenDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
end function
</code>
Beispiele für Aufrufe:

<code>[oobas]
oDoc = fnOpenDoc("C:\Documents and Settings\danny\Desktop\MyCalc.sxc") ' Windows
oDoc = fnOpenDoc("/home/danny/Desktop/MyCalc.sxc") ' Linux
</code>

== Die aktuelle Selektion ==
Häufig werden Sie eine Funktion schreiben wollen, die etwas mit dem aktuell selektierten Bereich anstellt. <tt>ThisComponent</tt> enthält die Methode <tt>getCurrentSelection</tt>. Da viele unterschiedliche Objekte selektiert sein könnten, werden Sie zuerst prüfen wollen, ob das selektierte Objekt über den Dienst verfügt, der die Methode enthält, mit der Sie das Objekt bearbeiten wollen.

Editieren Sie die Subroutine main im nachfolgenden Code und führen Sie sie mehrfach in einem Textdokument aus, wobei Sie unterschiedliche Objekte selektieren. (Um mehr als einen Textblock zu selektieren, betätigen Sie die '''Strg'''-Taste).

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
'xray.xray oCurSelection
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
msgbox "There are " & oCurSelection.getCount() & _
" selections in the current text document."
end if
end if
end sub
</code>
Wenn nichts selektiert ist, beträgt die Anzahl der Selektionen eins (nämlich der Einfügepunkt), wenn ein Textblock selektiert ist, beträgt die Anzahl ebenfalls eins, wenn zwei Textblöcke selektiert sind, beträgt sie drei: der Einfügepunkt sowie die beiden selektierten Textblöcke.

Übung 1: Modifizieren Sie den obigen Code so, dass er mit selektierten Zellbereichen in einem Tabellendokument funktioniert.

Frage 1: Wie hoch ist die Anzahl der Selektionen, wenn zwei Zellblöcke selektiert sind?

==Properties==
Wenn Sie die Zeile <tt>'xray.xray oCurSelection</tt> entkommentieren, so dass xray läuft, sehen Sie, dass das Objekt, worauf <tt>oCurSelection</tt> zeigt, eine "Property" namens <tt>Count</tt> besitzt, mit einer Beschreibung "pseudo-prop, read only". In OpenOffice.org Basic könnten Sie <tt>oCurSelection.count</tt> schreiben, da dies aber in keiner anderen Sprache, mit der Sie auf die OpenOffice.org API zugreifen können, möglich ist, werde ich versuchen, in diesem Wiki nur über Methoden zuzugreifen. (Möglicherweise vergesse ich das auch das eine oder andere Mal).

Das nächste Beispiel zeigt, wie man einen Property-Wert für die aktuellen Selektionen ändert.

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
nCount = oCurSelection.Count
'xray.xray oCurSelection.getByIndex(0)
'Warnung: Am Einfügepunkt wird die selbe Aktion zwei mal angewandt -
'das macht in diesem Fall nichts, kann aber durchaus problematisch werden.
for i = 0 to nCount - 1
oCurSelection.getByIndex(i).setPropertyValue("CharStyleName", "Strong Emphasis")
next
end if
end if
end sub
</code>

In OpenOffice.org Basic kann man die Zuweisung auch abkürzen:

<code>[oobas]
oCurSelection(i).CharStyleName = "Strong Emphasis"
</code>
Hier in diesem Wiki versuche ich, sowohl zur Indexierung als auch zur Zuweisung von Properties die vollständigen Methoden zu verwenden. Dadurch kann der Code leichter in andere Sprachen portiert werden und es hilft Ihnen auch, zu verstehen, was vor sich geht (nochmal: Bitte um Entschuldigung, wenn ich mal von dieser Regel abweiche, weil ich es eigentlich nicht gewohnt bin)

Übung 2: Schreiben Sie den obigen Code so um, dass die Warnung entfernt werden kann.

Siehe [[DE:Aktuelle Selektion]] ([[ Current selection]]).

=Iterative Access to Subordinate Objects (Enumeration access)=
Sometimes to access the desired object an enumeration is required. For example paragraphs, within a document or within a selection.

When a Writer document is active and some text is selected, both <tt>thisDocument.getText()</tt> and <tt>thisComponent.getCurrentSelection().getByIndex(i)</tt> have the service: com.sun.star.text.TextRange which has the interface: com.sun.star.container.XContentEnumerationAccess, it is possible to create an enumeration of the paragraphs for the current document or for a particular selection.

<code>[oobas]
' Create enumeration object
oTextElementEnum = thisComponent.getText().createEnumeration()
'or thisComponent.getCurrentSelection().getByIndex(i).createEnumeration()

' loop over all text elements
while oTextElementEnum.hasMoreElements()
oTextElement = oTextElementEnum.nextElement
if oTextElement.supportsService("com.sun.star.text.TextTable") then
MsgBox "The current block contains a table."
end if
if oTextElement.supportsService("com.sun.star.text.Paragraph") then
MsgBox "The current block contains a paragraph."
end if
wend
</code>
Exercise 3: Extend the above example to display in a message box all text portions that are bold.

=Named access=
Some objects provide named access to a particular type of subordinate object, some others indexed access, and some both named and indexed access.

For example if the current document in OpenOffice.org is a spreadsheet then to access a particular sheet can be done by index access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByIndex(0)
</code>
or named access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByName("Sheet1")
</code>
To check if an object with a particular name already exists use <tt>hasByName</tt>, for example:

<code>[oobas]
if thisComponent.getSheets.hasByName("Sheet1") then
</code>
To loop through all the available object names can be done like:

<code>[oobas]
mNames = thisComponent.getSheets.getElementnames
for i = lbound(mNames) to ubound(mNames)
msgbox mNames(i)
next
</code>

Some named subordinate objects also provide the interface: com.sun.star.container.XNameContainer. This interface defines that such objects should have the following methods: <tt>insertByName</tt>, <tt>replaceByname</tt> and <tt>removeByName</tt>.

E.g.

<code>[oobas]
thisComponent.getSheets.insertByName("NewSheet")
</code>

=Create new objects=
Some objects have services which implement interfaces to provide specific methods for creating a particular type of object.

For example if the current document is a Writer document then <tt>thisComponent.getText</tt> is an object that provides the service com.sun.star.text.Text which implements the interface com.sun.star.text.XSimpleText which defines the methods <tt>createTextCursor</tt> and <tt>createTextCursorByRange</tt>. Both of these methods create a text cursor for accessing the text of the document. These cursors are quite independent of the view cursor . The view cursor is visible on the screen and is manipulated by the user (and can be manipulated by program control), where as a text cursor is not visible on the screen and is solely used by program control. The following code snippet demonstrates creating a new text cursor, such that it starts at the same location as the viewCursor and is then moved independent of the view cursor.

<code>[oobas]
oVC = thisComponent.getCurrentController.getViewCursor
oCursor = oVC.getText.createTextCursorByRange(oVC)
oCursor.gotoStartOfSentence(false)
oCursor.gotoEndOfSentence(true)
msgbox oCursor.getString
</code>

Some objects are context dependent and get created using the method <tt>createInstance</tt> which is defined in the interface com.sun.star.lang.XMultiServiceFactory. For example to add a rectangle to the first page of a drawing document:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
dim aSize as new com.sun.star.awt.Size

aPoint.x = 1000
aPoint.y = 1000

aSize.Width = 10000
aSize.Height = 10000

oRectangleShape = thisComponent.createInstance("com.sun.star.drawing.RectangleShape")
oRectangleShape.Size = aSize
oRectangleShape.Position = aPoint

thisComponent.getDrawPages.getByIndex(0).add(oRectangleShape)
</code>

This example also uses UNO structs see below for more information on UNO stucts.

Some objects are context independent to create these objects use the OpenOffice.org Basic command createUnoService. For example to create the equivalent to StarDesktop:

<code>[oobas]
oDesktop = createUnoService("com.sun.star.frame.Desktop")
</code>

The process that I use to determine how to access or create an object is as follows:

Does the object already exist if so I should be able to access it from something like <tt>thisComponent</tt>.

Will the new object belong to another object, if so does the owner have a specific method for creating the object, if so use it.

The new object will belong to another object, but that object doesn't provide a specific method for creating it, but does provide <tt>createInstance</tt>. If the object doesn't provide <tt>createInstance</tt> are you sure you are using the correct object, or is it context independent.

I have found working out how to create an object to be quite difficult with existing documentation so I hope that this document/wiki will eventually make this clear.

==UNO structs==
UNO structures can be declared using the OpenOffice.org Basic command <tt>dim</tt>:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
</code>
Or by using the OpenOffice.org Basic command <tt>createUnoStruct</tt>:

<code>[oobas]
aPoint = createUnoStruct("com.sun.star.awt.Point")
</code>

{| border="1"
|'''Note:'''
|When declaring UNO structs case is important. Note that everything upto the name of the struct is lowercase, and that the name of the struct is in TitleCase.
|}

==Creating Listeners and Handlers==
Through the user interface it is possible to assign macros to some events:

OpenOffice.org versions 1.1.x: '''Tools > Configure… > Events'''.

OpenOffice.org versions 1.9.x and above: '''Tools > Customize… > Events'''.

It is also possible to assign macros to a wider range of events using the OpenOffice.org Basic command CreateUnoListener. This same command is used for creating both listeners and handlers. A listener checks for an event and always allows other listeners to respond to the event as well. A handler listens for an event, and can optionally consume the event so that other listeners don't get to act on it.

The following example creates a keyHandler:

<code>[oobas]
global IannzExampleKeyHandler

sub SetupKeyHandler
oController = thisComponent.currentController
IannzExampleKeyHandler = CreateUnoListener("KeyHandler_","com.sun.star.awt.XKeyHandler")
oController.addKeyHandler(IannzExampleKeyHandler) ' Register the listener
end sub

sub RemoveKeyHandler
thisComponent.currentController.removeKeyHandler(IannzExampleKeyHandler)
end sub

sub KeyHandler_disposing
end sub

function KeyHandler_keyReleased(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyReleased = False
end function

function KeyHandler_keyPressed(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyPressed = false 'Let other listeners handle the event
if oKeyEvent.modifiers = com.sun.star.awt.KeyModifier.MOD2 then 'Control key was pressed
if oKeyEvent.keyCode = com.sun.star.awt.Key.Q then
msgbox "Alt + Q was pressed"
KeyHandler_keyPressed = true 'Don't let other listeners process this event
end if
end if
end function
</code>
A variable declared as global keeps its value even after the macro exits. In this case we want to be able to use this variable later to remove the handler. As variables declared globally could be used in other libraries to try and avoid conflict I start all my global variables with Iannz my registered name for the OpenOffice.org web site.

<tt>sub SetupKeyHandler</tt> sets up the handler. The first parameter to CreateUnoListener is the staring name for the methods that will be called when that type of event occurs in this example .<tt>"KeyHandler_"</tt>.

The second parameter is the name of the interface for the listener or handler, "com.sun.star.awt.XKeyHandler". The name is case sensitive, everything up to and including the module name is always lowercase, the name of the interface always starts with "X" and the remainder is in TitleCase.

Use the SDK to find out what methods the interface must supply. You must supply routines for all of these methods even if you don't intend to use them. You also need to supply a disposing method. The names of these routines start with the string given in the first parameter to CreateUnoListener , in this example <tt>"KeyHandler_"</tt>.

Thus in the example there is <tt>KeyHandler_disposing</tt> and <tt>KeyHandler_keyReleased</tt> which don't actually do anything but are required, and <tt>KeyHandler_keyPressed</tt> which actually does the job.

<tt>sub RemoveKeyHandler</tt> demonstrates how to remove the handler.

=OpenOffice.org constants=
The above example uses OpenOffice.org constants.

E.g. com.sun.star.awt.KeyModifier.MOD2

OpenOffice.org constants are case sensitive. Everything up to and including the module name is always lowercase. The constant group is in TitleCase. The actual constant name is always UPPERCASE.

Programmers not using OpenOffice.org Basic may not have access to these constants.

=Using the recorder=
See [[ The OpenOffice.org recorder and UNO dispatch calls]] section for a discussion on recording UNO Dispatch commands versus writing API calls.

[[Category:Basic:Tutorials]]