Apache OpenOffice Wiki - User contributions [en]

Documentation/DevGuide/WritingUNO/Implementing without Helpers

2011-03-23T01:22:35Z

Newacct:

{{Documentation/DevGuide/WritingUNOTOC
|WritingUNO2c=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/WritingUNO/Write Registration Info Using a Helper Method
|NextPage=Documentation/DevGuide/WritingUNO/Storing the Service Manager for Further Use
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/WritingUNO/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Implementing without Helpers}}
=== XInterface ===

As soon as the component implements any UNO interface, <idl>com.sun.star.uno.XInterface</idl> is included automatically. The Java interface definition generated by javamaker for <idl>com.sun.star.uno.XInterface</idl> only contains a <code>TypeInfo</code> member used by Java UNO internally to store certain UNO type information:
<source lang="java">
// source file com/sun/star/uno/XInterface.java corresponding to the class generated by

package com.sun.star.uno;

public interface XInterface
{
// static Member
public static final com.sun.star.lib.uno.typeinfo.TypeInfo UNOTYPEINFO[] = null;
}
</source>
Note that <code>XInterface</code> does not have any methods, in contrast to its IDL description. That means, if <code>implements com.sun.star.uno.XInterface</code> is added to a class definition, there is nothing to implement.

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

The methods <code>acquire()</code> and <code>release()</code> are used for reference counting and control the lifetime of an object, because the Java garbage collector does this, there is no reference counting in Java components.

=== XTypeProvider ===

Helper classes with default <idl>com.sun.star.lang.XTypeProvider</idl> implementations are still under development for Java. Meanwhile, every Java UNO object implementation can implement the <code>XTypeProvider</code> interface as shown in the following code. In your implementation, adjust <code>getTypes()</code>: 
<source lang="java">
...

// XTypeProvider implementation

// maintain a static implementation id for all instances of ImageShrink
// initialized by the first call to getImplementationId()
protected static byte[] _implementationId;

public com.sun.star.uno.Type[] getTypes() {

// instantiate Type instances for each interface you support and place them in a Type[] array
// (this object supports XServiceInfo, XTypeProvider, and XImageShrinkFilter)
return new com.sun.star.uno.Type[] {
new com.sun.star.uno.Type(com.sun.star.lang.XServiceInfo.class),
new com.sun.star.uno.Type(com.sun.star.lang.XTypeProvider.class),
new com.sun.star.uno.Type(org.openoffice.test.XImageShrinkFilter.class) };
}

synchronized public byte[] getImplementationId() {
if (_implementationId == null) {
_implementationId= new byte[16];
int hash = hashCode(); // hashCode of this object
_implementationId[0] = (byte)(hash & 0xff);
_implementationId[1] = (byte)((hash >>> 8) & 0xff);
_implementationId[2] = (byte)((hash >>> 16) & 0xff);
_implementationId[3] = (byte)((hash >>>24) & 0xff);
}
return _implementationId;
}

...
</source>
The suggested implementation of the <code>getImplementationId()</code> method is not optimal, it uses the <code>hashCode()</code> of the first instance that initializes the static field. The future UNO helper class will improve this.

=== XComponent ===

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

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

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

//XComponent implementation

// hold a list of eventListeners
private java.util.ArrayList eventListeners = new java.util.ArrayList();

public void dispose {
java.util.ArrayList listeners;
synchronized (this) {
listeners = eventListeners;
eventListeners = null;
}
for (java.util.Iterator i = listeners.iterator(); i.hasNext();) {
fireDisposing((XEventListener) i.next());
}
releaseReferences();
}

public void addEventListener(XEventListener listener) {
bool fire = false;
synchronized (this) {
if (eventListeners == null) {
fire = true;
} else {
eventListeners.add(listener);
}
}
if (fire) {
fireDisposing(listener);
}
}

public synchronized void removeEventListener(XEventListener listener) {
if (eventListeners != null) {
eventListeners.remove(listener);
}
}

private void fireDisposing(XEventListener listener) {
com.sun.star.uno.EventObject event = new com.sun.star.uno.EventObject(this);
try {
listener.disposing(event);
} catch (com.sun.star.uno.DisposedException e) {
// it is not an error if some listener is disposed simultaneously
}
}

private void releaseReferences() {
xComponentContext = null;
// ...
}
</source>
{{PDL1}}

[[Category:Documentation/Developer's Guide/Writing UNO Components]]

Writing warning-free code

2011-02-08T05:23:18Z

Newacct: /* Invalid enum case values */

We are currently on the way towards a completely warning-free OOo C/C++ code base. And once we have reached that, we want to keep the code clean!

We reached a first milestone by integrating CWS [http://eis.services.openoffice.org/EIS2/servlet/cws.showCWS?Id=2903&Path=SRC680%2Fwarnings01 warnings01] into SRC680m173. Since then, and at least on the <code>unxlngi6</code>, <code>unxsoli4</code>, <code>unxsols4</code>, and <code>wntmsci10</code> platforms, the C/C++ compilers are used with rather aggressive warning levels, and in most CVS modules warnings are treated as errors that break the build. Some CVS modules have not yet been made warning-free.

==What changed?==

Since SRC680m173, any new or modified C/C++ code that produces warnings will break the build. (Unless, of course, you fail to pass <code>--enable-werror</code> to <code>configure</code>.) Ideally, to be sure that integrating a CWS will not break the build, the CWS should now be built on every warning-free platform (i.e., at least <code>unxlngi6</code>, <code>unxsoli4</code>, <code>unxsols4</code>, and <code>wntmsci10</code>), with all supported compiler versions, in both product and non-product variants, and with and without the <code>debug=x</code> build switch before nominating it for integration. Practically, a reasonable subset of these will have to suffice.

For <code>unxlngi6</code>, we concentrated on GCC 3.4.1, GCC 4.0.2/4.0.3, and GCC 4.1.1, while other GCC versions probably produce slightly different warnings (that could break the build now on those GCC versions).

Porters are encouraged to make additional platforms warning-free. Since most ports are using GCC, there should not be too many surprises. Any necessary changes to the platform-specific <code>.mk</code> file in <code>solenv/inc</code> can be modelled after <code>solenv/inc/unxlngi6.mk</code>. In short, you need a bunch of <code>CFLAGSxxx</code> (see [http://www.openoffice.org/servlets/ReadMsg?list=interface-announce&msgNo=758 interface-announce C/C++ compiler warnings]) and <code>MODULES_WITH_WARNINGS</code> or <code>COMPILER_WARN_ERRORS</code> (see [http://www.openoffice.org/servlets/ReadMsg?list=interface-announce&msgNo=942 interface-announce MODULES_WITH_WARNINGS]).

The <code>wall=x</code> build switch no longer has any effect on the warning-free platforms. Once all platforms are warning-free, we can remove it completely.

==The missing modules==

If your job is to clean up a given CVS module, here are some practical guidelines:
* Remove the module from the <code>MODULES_WITH_WARNINGS</code> list in the platform-specific <code>.mk</code> files in <code>solenv/inc</code>.
* Make sure your module builds and delivers successfully with <code>build && deliver</code> (and all the variants mentioned above).
* If your module contains external code which we do not want to clean up, set <code>EXTERNAL_WARNINGS_NOT_ERRORS := TRUE</code> at the beginning of the corresponding <code>makefile.mk</code>, so that warnings do not lead to errors there.
* In any case, for any header file delivered from your module, make sure that <code>testhxx</code> on the delivered header file is successful. (Note that <code>testhxx</code> only works for headers delivered to the solver, not for local headers within a CVS module, as it calls the compiler with only a fixed set of include directories.)
* If you encounter a warning that cannot reasonably be worked around, discuss that problem on <code>dev@openoffice.org</code>. One outcome of that discussion can be that we globally disable that particular warning. To see which warnings are already globally disabled on a given platform, look at the settings for <code>CFLAGSWARNCC</code>, <code>CFLAGSWARNCXX</code>, <code>CFLAGSWALLCC</code>, and/or <code>CFLAGSWALLCXX</code> in the platform-specific <code>.mk</code> file in <code>solenv/inc</code> (<code>unxlngi6.mk</code>, <code>unxsoli4.mk</code>, <code>unxsols4.mk</code>, and <code>wntmsci10.mk</code>).

See the current [[Warning-free_code_status|warning-free code status]].

==Tips for Warning-free code==

The following is a list of issues you might come across when making existing
code warning-free, or when writing new, warning-free code:

===Integral conversions===

Sometimes, a cast between integral types is needed to avoid a warning. In such a case, use <code>sal::static_int_cast</code> (C++) or <code>SAL_INT_CAST</code> (C) to make that cast stick out—it will need to be adapted when the type of any of the involved expressions changes later on:
<source lang="cpp">
sal_Int32 n;
std::vector<char> v;
if (n >= 0 && sal::static_int_cast<sal_uInt32>(n) == v.size()) ...
</source>

Note that you might get the warning C4244 (possible loss of data) on Windows also for the following situation:
<source lang="cpp">
short a = 0, b = 0;
a += b; // warning C4244 on Windows
</source>
This is because <code>a</code> and <code>b</code> are converted to <code>int</code>, then added and the result is then again cast back to <code>short</code>. This is especially nasty, as it also happens when you use <code>xub_StrLen</code>, but only if it is a typedf to <code>USHORT</code> and not to <code>sal_uInt32</code>, i.e. only as long as <code>STRING32</code> is not defined in solar.h.
The warning does not occur when you use <code>operator+</code> instead of <code>operator+=</code>.
<source lang="cpp">
short a = 0, b = 0;
a = a + b;
</source>

===Invalid enum case values===

Code like
<source lang="cpp">
enum E { A=1, B=2, C=4 } e;
switch (e) {
case A: ...
case B|C: ...
}
</source>
will cause <code>wntmsci11</code> to complain with <code>warning C4063: case '6' is not a valid value for switch of enum 'E'</code>. The cause of the warning is that <code>E</code> is not meant be an enumerated type, but a bit field type. <code>enum</code> is commonly used in C and C++ to initialize constants; in this case, constants for individual bits.

A better way to write this would be to typedef <code>E</code> to be an unsigned int (a better type for bit fields); and then define the constants for the individual bits using an anonymous <code>enum</code>. (A downside is that the documentation for the type <code>E</code> will not contain the constants the user needs to use.)
<source lang="cpp">
typedef unsigned int E;
E e;
enum { A=1, B=2, C=4 };
switch (e) {
case A: ...
case B|C: ...
}
</source>

If you do not have access to the definition of the type <code>E</code>, it can still be worked around by promoting <code>e</code> to its underlying integral type:
<source lang="cpp">
...
switch (+e) {
...
</source>

===Casting between pointer and integer types===

====C++====

* From pointer-to-(possibly-cv-qualified-)void-or-object type <code>P</code> to unsigned integral type <code>U</code>:
<source lang="cpp">
P p;
U u = sal::static_int_cast(reinterpret_cast<sal_uIntPtr>(p));
</source>

* From unsigned integral type <code>U</code> to pointer-to-(possibly-cv-qualified-)void-or-object type <code>P</code>:
<source lang="cpp">
U u;
P p = reinterpret_cast(sal::static_int_cast<sal_uIntPtr>(u));
</source>

* From pointer-to-(possibly-cv-qualified-)void-or-object type <code>P</code> to signed integral type <code>S</code>:
<source lang="cpp">
P p;
S s = sal::static_int_cast<S>(reinterpret_cast<sal_IntPtr>(p));
</source>

* From signed integral type <code>S</code> to pointer-to-(possibly-cv-qualified-)void-or-object type <code>P</code>:
<source lang="cpp">
S s;
P p = reinterpret_cast(sal::static_int_cast<sal_IntPtr>(s));
</source>

====C====

* From pointer-to-(possibly-qualified-)void-or-object type <code>P</code> to unsigned integer type <code>U</code>:
<source lang="c">
P p;
U u = SAL_INT_CAST(U, (sal_uIntPtr) p);
</source>

* From unsigned integer type <code>U</code> to pointer-to-(possibly-qualified-)void-or-object type <code>P</code>:
<source lang="c">
U u;
P p = (P) SAL_INT_CAST(sal_uIntPtr, u);
</source>

* From pointer-to-(possibly-qualified-)void-or-object type <code>P</code> to signed integer type <code>S</code>:
<source lang="cpp">
P p;
S s = SAL_INT_CAST(S, (sal_IntPtr) p);
</source>

* From signed integer type <code>S</code> to pointer-to-(possibly-qualified-)void-or-object type <code>P</code>:
<source lang="cpp">
S s;
P p = (P) SAL_INT_CAST(sal_IntPtr, s);
</source>

===Pointer to function===

A pointer to function is not compatible with a pointer to object, so code like
<source lang="cpp">
void * osl::Module::getSymbol(rtl::OUString const &);
typedef void (* MyFunc)();
MyFunc f = module.getSymbol("myFunc");
</source>
will not compile. The only places were converting between pointer to function and pointer to object (typically <code>void *</code>) should be necessary are <code>osl::Module::getSymbol</code> and <code>osl::Module::getUrlFromAddress</code>, and in both cases there are additional functions (<code>osl::Module::getFunctionSymbol</code> and an overload with <code>oslGenericFunction</code> of <code>osl::Module::getUrlFromAddress</code>) that handle the problem internally. Use them!

===Name hiding===

In C++, use a <code>using</code> declaration to make visible (virtual) function declarations from a base clase that would be hidden by a function declaration in a derived class:
<source lang="cpp">
class Base {
public:
virtual void f(int);
virtual void f(double);
};
class Derived: public Base {
public:
using Base::f;
virtual void f(int);
};
</source>

Make sure to apply the correct access control to the <code>using</code> declaration:
<source lang="cpp">
class Base {
protected:
void f();
};
class Derived: public Base {
public:
void f(int);
protected:
using Base::f;
};
</source>

If you can, avoid such constructs as in the above example, by chosing different names for the two functions <code>f</code>. If on the other hand the function f is clearly meant to be overloaded, then make all instances of <code>f</code> virtual in the base class.

===Unused parameters===

There are three cases where a parameter of a function is not actually used in the definition of the function:

* The function has to have a certain signature (it is a virtual function, shall be used with a certain function pointer type, or is part of a stable API that cannot be changed). In those cases, leave out the paramter name in the function definition (C++) or use
<source lang="cpp">
(void) paramName; /* avoid warning about unused parameter */
</source>
at the start of the function body (C).

* The function is created by the Macro IMPL_LINK( Class, Method, ArgType, ArgName ) from tools/inc/link.hxx or similar. Use EMPTYARG as Parametername as in
<source lang="cpp">
IMPL_LINK( Class, Method, ArgType, EMPTYARG )
</source>
EMPTYARG is defined empty, so this will result in leaving out the parameter name as suggested above.

* The function uses the paramter only in an <code>#ifdef</code>-block, or only in <code>OSL_ASSERT</code> etc. debug code. If the first case occurs in C++ code, fix it by using the same <code>#ifdef</code> around the parameter name in the function header. In all other cases, fix it by using
<source lang="cpp">
(void) paramName; /* avoid warning about unused parameter */
</source>
at the start of the function body.

* The function once used the parameter, but does no longer do so. In that case, clean up the function declaration and all uses of the function.

===When all else fails===

There are cases where the only sensible solution is to suppress warnings for a given chunk of code:

* As explained above, in external code which we do not want to clean up, use <code>EXTERNAL_WARNINGS_NOT_ERRORS := TRUE</code> so that warnings do not lead to errors there.

* Header files included directly from the system, or header files delivered from external code included in the OOo code base but which we cannot reasonably make <code>testhxx</code>-clean: Surround that code (e.g., the <code>#include</code>-directives for those headers) by
<source lang="cpp">
#if defined __GNUC__
#pragma GCC system_header
#elif defined __SUNPRO_CC
#pragma disable_warn
#elif defined _MSC_VER
#pragma warning(push, 1)
#endif
</source>
and
<source lang="cpp">
#if defined __SUNPRO_CC
#pragma enable_warn
#elif defined _MSC_VER
#pragma warning(pop)
#endif
</source>
(probably together with an explanatory comment). Due to the nature of the GCC solution, this does not work directly within the compilation unit's main (<code>.c</code>, <code>.cxx</code>) file, only within a (<code>.h</code>, <code>.hxx</code>) file included directly or indirectly. Even more important, because the <code>system_header</code> pragma affects the ''rest of the current header'', the entire warnings guard mechanism should be separated into a ''header file on its own'', including just the file in question. From the original file then include that wrapper file.

* Code generated by <code>flex</code> or <code>bison</code>: The solution here is similar to the solution in the previous item—disable all warnings in the generated code. However, this has two implications: For one, it means that also all warnings from our client code integrated into the <code>flex</code>/<code>bison</code> output are suppressed; this is not really that large an issue, given the relatively small number of <code>flex</code>/<code>bison</code> files we use. For another, due to the nature of the GCC solution, it means that you need to introduce a wrapper file. The individual steps for a given <code>flex</code>/<code>bison</code> file named <code>example.ly</code>, translated to <code>$(MISC)$/example.cxx</code>, are as follows: First, change <code>example.ly</code> by adding
<source lang="cpp">
#if defined __GNUC__
#pragma GCC system_header
#elif defined __SUNPRO_CC
#pragma disable_warn
#elif defined _MSC_VER
#pragma warning(push, 1)
#endif
</source>
(probably together with an explanatory comment) at the very end of the initial <code>%{...%}</code> section (for <code>_MSC_VER</code>, <code>#pragma warning(push, 1)</code> might not disable all the warnings that occur; in that case, add <code>#pragma warning(disable: NNN1 NNN2 ...)</code> after it to disable specific warnings <code>NNN1</code>, <code>NNN2</code>, etc.). Second, create a new file named <code>wrap_example.cxx</code> in the same source directory as <code>exmaple.ly</code>, containing
<source lang="cpp">
#include "example.cxx"
</source>
Third, change the corresponding <code>makefile.mk</code> by adding
<code>[]
INCPRE=$(MISC)
</code>
to the top, by changing occurences of <code>example.obj</code> to <code>wrap_example.obj</code>, and by adding
<code>[]
$(OBJ)$/wrap_example.obj: $(MISC)$/example.cxx
</code>
and/or
<code>[]
$(SLO)$/wrap_example.obj: $(MISC)$/example.cxx
</code>
at the bottom.

[[Category:Coding Standards]]

Writing warning-free code

2011-02-08T05:22:32Z

Newacct: /* Invalid enum case values */

We are currently on the way towards a completely warning-free OOo C/C++ code base. And once we have reached that, we want to keep the code clean!

We reached a first milestone by integrating CWS [http://eis.services.openoffice.org/EIS2/servlet/cws.showCWS?Id=2903&Path=SRC680%2Fwarnings01 warnings01] into SRC680m173. Since then, and at least on the <code>unxlngi6</code>, <code>unxsoli4</code>, <code>unxsols4</code>, and <code>wntmsci10</code> platforms, the C/C++ compilers are used with rather aggressive warning levels, and in most CVS modules warnings are treated as errors that break the build. Some CVS modules have not yet been made warning-free.

==What changed?==

Since SRC680m173, any new or modified C/C++ code that produces warnings will break the build. (Unless, of course, you fail to pass <code>--enable-werror</code> to <code>configure</code>.) Ideally, to be sure that integrating a CWS will not break the build, the CWS should now be built on every warning-free platform (i.e., at least <code>unxlngi6</code>, <code>unxsoli4</code>, <code>unxsols4</code>, and <code>wntmsci10</code>), with all supported compiler versions, in both product and non-product variants, and with and without the <code>debug=x</code> build switch before nominating it for integration. Practically, a reasonable subset of these will have to suffice.

For <code>unxlngi6</code>, we concentrated on GCC 3.4.1, GCC 4.0.2/4.0.3, and GCC 4.1.1, while other GCC versions probably produce slightly different warnings (that could break the build now on those GCC versions).

Porters are encouraged to make additional platforms warning-free. Since most ports are using GCC, there should not be too many surprises. Any necessary changes to the platform-specific <code>.mk</code> file in <code>solenv/inc</code> can be modelled after <code>solenv/inc/unxlngi6.mk</code>. In short, you need a bunch of <code>CFLAGSxxx</code> (see [http://www.openoffice.org/servlets/ReadMsg?list=interface-announce&msgNo=758 interface-announce C/C++ compiler warnings]) and <code>MODULES_WITH_WARNINGS</code> or <code>COMPILER_WARN_ERRORS</code> (see [http://www.openoffice.org/servlets/ReadMsg?list=interface-announce&msgNo=942 interface-announce MODULES_WITH_WARNINGS]).

The <code>wall=x</code> build switch no longer has any effect on the warning-free platforms. Once all platforms are warning-free, we can remove it completely.

==The missing modules==

If your job is to clean up a given CVS module, here are some practical guidelines:
* Remove the module from the <code>MODULES_WITH_WARNINGS</code> list in the platform-specific <code>.mk</code> files in <code>solenv/inc</code>.
* Make sure your module builds and delivers successfully with <code>build && deliver</code> (and all the variants mentioned above).
* If your module contains external code which we do not want to clean up, set <code>EXTERNAL_WARNINGS_NOT_ERRORS := TRUE</code> at the beginning of the corresponding <code>makefile.mk</code>, so that warnings do not lead to errors there.
* In any case, for any header file delivered from your module, make sure that <code>testhxx</code> on the delivered header file is successful. (Note that <code>testhxx</code> only works for headers delivered to the solver, not for local headers within a CVS module, as it calls the compiler with only a fixed set of include directories.)
* If you encounter a warning that cannot reasonably be worked around, discuss that problem on <code>dev@openoffice.org</code>. One outcome of that discussion can be that we globally disable that particular warning. To see which warnings are already globally disabled on a given platform, look at the settings for <code>CFLAGSWARNCC</code>, <code>CFLAGSWARNCXX</code>, <code>CFLAGSWALLCC</code>, and/or <code>CFLAGSWALLCXX</code> in the platform-specific <code>.mk</code> file in <code>solenv/inc</code> (<code>unxlngi6.mk</code>, <code>unxsoli4.mk</code>, <code>unxsols4.mk</code>, and <code>wntmsci10.mk</code>).

See the current [[Warning-free_code_status|warning-free code status]].

==Tips for Warning-free code==

The following is a list of issues you might come across when making existing
code warning-free, or when writing new, warning-free code:

===Integral conversions===

Sometimes, a cast between integral types is needed to avoid a warning. In such a case, use <code>sal::static_int_cast</code> (C++) or <code>SAL_INT_CAST</code> (C) to make that cast stick out—it will need to be adapted when the type of any of the involved expressions changes later on:
<source lang="cpp">
sal_Int32 n;
std::vector<char> v;
if (n >= 0 && sal::static_int_cast<sal_uInt32>(n) == v.size()) ...
</source>

Note that you might get the warning C4244 (possible loss of data) on Windows also for the following situation:
<source lang="cpp">
short a = 0, b = 0;
a += b; // warning C4244 on Windows
</source>
This is because <code>a</code> and <code>b</code> are converted to <code>int</code>, then added and the result is then again cast back to <code>short</code>. This is especially nasty, as it also happens when you use <code>xub_StrLen</code>, but only if it is a typedf to <code>USHORT</code> and not to <code>sal_uInt32</code>, i.e. only as long as <code>STRING32</code> is not defined in solar.h.
The warning does not occur when you use <code>operator+</code> instead of <code>operator+=</code>.
<source lang="cpp">
short a = 0, b = 0;
a = a + b;
</source>

===Invalid enum case values===

Code like
<source lang="cpp">
enum E { A=1, B=2, C=4 } e;
switch (e) {
case A: ...
case B|C: ...
}
</source>
will cause <code>wntmsci11</code> to complain with <code>warning C4063: case '6' is not a valid value for switch of enum 'E'</code>. The cause of the warning is that <code>E</code> is not meant be an enumerated type, but a bit field type. <code>enum</code> is commonly used in C and C++ to initialize constants; in this case, constants for individual bits.

A better way to write this would be to typedef <code>E</code> to be an unsigned int (a better type for bit fields); and then define the constants for the individual bits using an anonymous <code>enum</code>. (A downside is that the documentation for the type <code>E</code> will not contain the constants the user needs to use.)
<source lang="cpp">
typedef unsigned int E;
E e;
enum { A=1, B=2, C=4 };
switch (e) {
case A: ...
case B|C: ...
}
</source>

If you do not have access to the definition of the type <code>E</code>, it can still be worked around by promoting <code>e</code> to is underlying integral type:
<source lang="cpp">
...
switch (+e) {
...
</source>

===Casting between pointer and integer types===

====C++====

* From pointer-to-(possibly-cv-qualified-)void-or-object type <code>P</code> to unsigned integral type <code>U</code>:
<source lang="cpp">
P p;
U u = sal::static_int_cast(reinterpret_cast<sal_uIntPtr>(p));
</source>

* From unsigned integral type <code>U</code> to pointer-to-(possibly-cv-qualified-)void-or-object type <code>P</code>:
<source lang="cpp">
U u;
P p = reinterpret_cast(sal::static_int_cast<sal_uIntPtr>(u));
</source>

* From pointer-to-(possibly-cv-qualified-)void-or-object type <code>P</code> to signed integral type <code>S</code>:
<source lang="cpp">
P p;
S s = sal::static_int_cast<S>(reinterpret_cast<sal_IntPtr>(p));
</source>

* From signed integral type <code>S</code> to pointer-to-(possibly-cv-qualified-)void-or-object type <code>P</code>:
<source lang="cpp">
S s;
P p = reinterpret_cast(sal::static_int_cast<sal_IntPtr>(s));
</source>

====C====

* From pointer-to-(possibly-qualified-)void-or-object type <code>P</code> to unsigned integer type <code>U</code>:
<source lang="c">
P p;
U u = SAL_INT_CAST(U, (sal_uIntPtr) p);
</source>

* From unsigned integer type <code>U</code> to pointer-to-(possibly-qualified-)void-or-object type <code>P</code>:
<source lang="c">
U u;
P p = (P) SAL_INT_CAST(sal_uIntPtr, u);
</source>

* From pointer-to-(possibly-qualified-)void-or-object type <code>P</code> to signed integer type <code>S</code>:
<source lang="cpp">
P p;
S s = SAL_INT_CAST(S, (sal_IntPtr) p);
</source>

* From signed integer type <code>S</code> to pointer-to-(possibly-qualified-)void-or-object type <code>P</code>:
<source lang="cpp">
S s;
P p = (P) SAL_INT_CAST(sal_IntPtr, s);
</source>

===Pointer to function===

A pointer to function is not compatible with a pointer to object, so code like
<source lang="cpp">
void * osl::Module::getSymbol(rtl::OUString const &);
typedef void (* MyFunc)();
MyFunc f = module.getSymbol("myFunc");
</source>
will not compile. The only places were converting between pointer to function and pointer to object (typically <code>void *</code>) should be necessary are <code>osl::Module::getSymbol</code> and <code>osl::Module::getUrlFromAddress</code>, and in both cases there are additional functions (<code>osl::Module::getFunctionSymbol</code> and an overload with <code>oslGenericFunction</code> of <code>osl::Module::getUrlFromAddress</code>) that handle the problem internally. Use them!

===Name hiding===

In C++, use a <code>using</code> declaration to make visible (virtual) function declarations from a base clase that would be hidden by a function declaration in a derived class:
<source lang="cpp">
class Base {
public:
virtual void f(int);
virtual void f(double);
};
class Derived: public Base {
public:
using Base::f;
virtual void f(int);
};
</source>

Make sure to apply the correct access control to the <code>using</code> declaration:
<source lang="cpp">
class Base {
protected:
void f();
};
class Derived: public Base {
public:
void f(int);
protected:
using Base::f;
};
</source>

If you can, avoid such constructs as in the above example, by chosing different names for the two functions <code>f</code>. If on the other hand the function f is clearly meant to be overloaded, then make all instances of <code>f</code> virtual in the base class.

===Unused parameters===

There are three cases where a parameter of a function is not actually used in the definition of the function:

* The function has to have a certain signature (it is a virtual function, shall be used with a certain function pointer type, or is part of a stable API that cannot be changed). In those cases, leave out the paramter name in the function definition (C++) or use
<source lang="cpp">
(void) paramName; /* avoid warning about unused parameter */
</source>
at the start of the function body (C).

* The function is created by the Macro IMPL_LINK( Class, Method, ArgType, ArgName ) from tools/inc/link.hxx or similar. Use EMPTYARG as Parametername as in
<source lang="cpp">
IMPL_LINK( Class, Method, ArgType, EMPTYARG )
</source>
EMPTYARG is defined empty, so this will result in leaving out the parameter name as suggested above.

* The function uses the paramter only in an <code>#ifdef</code>-block, or only in <code>OSL_ASSERT</code> etc. debug code. If the first case occurs in C++ code, fix it by using the same <code>#ifdef</code> around the parameter name in the function header. In all other cases, fix it by using
<source lang="cpp">
(void) paramName; /* avoid warning about unused parameter */
</source>
at the start of the function body.

* The function once used the parameter, but does no longer do so. In that case, clean up the function declaration and all uses of the function.

===When all else fails===

There are cases where the only sensible solution is to suppress warnings for a given chunk of code:

* As explained above, in external code which we do not want to clean up, use <code>EXTERNAL_WARNINGS_NOT_ERRORS := TRUE</code> so that warnings do not lead to errors there.

* Header files included directly from the system, or header files delivered from external code included in the OOo code base but which we cannot reasonably make <code>testhxx</code>-clean: Surround that code (e.g., the <code>#include</code>-directives for those headers) by
<source lang="cpp">
#if defined __GNUC__
#pragma GCC system_header
#elif defined __SUNPRO_CC
#pragma disable_warn
#elif defined _MSC_VER
#pragma warning(push, 1)
#endif
</source>
and
<source lang="cpp">
#if defined __SUNPRO_CC
#pragma enable_warn
#elif defined _MSC_VER
#pragma warning(pop)
#endif
</source>
(probably together with an explanatory comment). Due to the nature of the GCC solution, this does not work directly within the compilation unit's main (<code>.c</code>, <code>.cxx</code>) file, only within a (<code>.h</code>, <code>.hxx</code>) file included directly or indirectly. Even more important, because the <code>system_header</code> pragma affects the ''rest of the current header'', the entire warnings guard mechanism should be separated into a ''header file on its own'', including just the file in question. From the original file then include that wrapper file.

* Code generated by <code>flex</code> or <code>bison</code>: The solution here is similar to the solution in the previous item—disable all warnings in the generated code. However, this has two implications: For one, it means that also all warnings from our client code integrated into the <code>flex</code>/<code>bison</code> output are suppressed; this is not really that large an issue, given the relatively small number of <code>flex</code>/<code>bison</code> files we use. For another, due to the nature of the GCC solution, it means that you need to introduce a wrapper file. The individual steps for a given <code>flex</code>/<code>bison</code> file named <code>example.ly</code>, translated to <code>$(MISC)$/example.cxx</code>, are as follows: First, change <code>example.ly</code> by adding
<source lang="cpp">
#if defined __GNUC__
#pragma GCC system_header
#elif defined __SUNPRO_CC
#pragma disable_warn
#elif defined _MSC_VER
#pragma warning(push, 1)
#endif
</source>
(probably together with an explanatory comment) at the very end of the initial <code>%{...%}</code> section (for <code>_MSC_VER</code>, <code>#pragma warning(push, 1)</code> might not disable all the warnings that occur; in that case, add <code>#pragma warning(disable: NNN1 NNN2 ...)</code> after it to disable specific warnings <code>NNN1</code>, <code>NNN2</code>, etc.). Second, create a new file named <code>wrap_example.cxx</code> in the same source directory as <code>exmaple.ly</code>, containing
<source lang="cpp">
#include "example.cxx"
</source>
Third, change the corresponding <code>makefile.mk</code> by adding
<code>[]
INCPRE=$(MISC)
</code>
to the top, by changing occurences of <code>example.obj</code> to <code>wrap_example.obj</code>, and by adding
<code>[]
$(OBJ)$/wrap_example.obj: $(MISC)$/example.cxx
</code>
and/or
<code>[]
$(SLO)$/wrap_example.obj: $(MISC)$/example.cxx
</code>
at the bottom.

[[Category:Coding Standards]]

XFastTokenHandler

2010-07-10T17:08:25Z

Newacct:

DRAFT

See [[FastParser]]

= Abstract =

An instance of this interface is used by a [[FastParser]] to convert xml names from utf8
to integer tokens used by [[XFastContextHandler]] and [[XFastAttributeList]]

= IDL =

<pre>

module com { module sun { module star { module xml { module sax {

/** a container for the attributes of an xml element.

 Attributes are seperated into known attributes and unknown attributes.
Known attributes have a local name that is known to the <type>XFastTokenHandler</token>
registered at the <type>XFastParser</type> which created the sax event containing
this attributes. If an attribute also has a namespace, that must be registered
at the <type>XFastParser</type>, else this attribute is also unknown even if
the local name is known.
*/
interface XFastAttributeList: com::sun::star::uno::XInterface
{
/** checks if an attribute is available. 

@param Token
contains the integer token from the <type>XFastTokenHandler</type>
registered at the <type>XFastParser</type>. 

If the attribute name has a namespace that was registered with the
<type>XFastParser</type>, Token contains the integer token of the
attributes local name from the <type>XFastTokenHandler</type> and
the integer token of the namespace combined with an arithmetic
or operation.

@returns
<TRUE/>, if the attribute is available
*/
boolean hasAttribute( [in] long Token );

/** retrieves the token of an attributes value. 

@param Token
contains the integer token from the <type>XFastTokenHandler</type>
registered at the <type>XFastParser</type>. 

If the attribute name has a namespace that was registered with the
<type>XFastParser</type>, Token contains the integer token of the
attributes local name from the <type>XFastTokenHandler</type> and
the integer token of the namespace combined with an arithmetic
or operation.

@returns
The integer token of the value from the attribute or <const>FastToken::Invalid</const>

@raises SAXEXception
if the attribute is not available

*/
long getValueToken( [in] long Token )
raises( SAXException );

/**retrieves the token of an attributes value. 

@param Token
contains the integer token from the <type>XFastTokenHandler</type>
registered at the <type>XFastParser</type>. 

If the attribute name has a namespace that was registered with the
<type>XFastParser</type>, Token contains the integer token of the
attributes local name from the <type>XFastTokenHandler</type> and
the integer token of the namespace combined with an arithmetic
or operation.

@param Default
This value will be returned if the attribute is not available

@returns
If the attribute is available it returns the integer token of the value
from the attribute or <const>FastToken::Invalid</const>.
If not the value of <param>Default</param> is returned.

*/
long getOptionalValueToken( [in] long Token, [in] long Default );

/** retrieves the value of an attributes. 

@param Token
contains the integer token from the <type>XFastTokenHandler</type>
registered at the <type>XFastParser</type>. 

If the attribute name has a namespace that was registered with the
<type>XFastParser</type>, Token contains the integer token of the
attributes local name from the <type>XFastTokenHandler</type> and
the integer token of the namespace combined with an arithmetic
or operation.

@returns
The string value from the attribute.

@raises SAXEXception
if the attribute is not available

*/
string getValue( [in] long Token )
raises( SAXException );

/** retrieves the value of an attributes. 

@param Token
contains the integer token from the <type>XFastTokenHandler</type>
registered at the <type>XFastParser</type>. 

If the attribute name has a namespace that was registered with the
<type>XFastParser</type>, Token contains the integer token of the
attributes local name from the <type>XFastTokenHandler</type> and
the integer token of the namespace combined with an arithmetic
or operation.

@returns
The string value from the attribute or an empty string if the
attribute is not available.
*/
string getOptionalValue( [in] long Token );

/** returns a sequence of attributes which names and or namespaces URLS
can not be translated to tokens.
*/
sequence< ::com::sun::star::xml::Attribute > getUnknownAttributes();
};

}; }; }; }; };

</pre>

= Sample implementation using gperf =

[http://www.gnu.org/software/gperf/gperf.html gperf] is a cool little tool to generate a perfect
hash algorithm at compile time for a fixed set of strings.

When writing a filter to import an xml format you usually have a list of valid xml names.
They can be easily extracted from a schema. Lets assume you already have a list
of valid xml names in the file ''tokens.txt'', for example

<pre>
User
Admin
Name
Login
</pre>

The following pearl script can convert that file to an input file for gperf and
also a header file with one const sal_Int32 identifier for each xml name.

<pre>
my $ARGV0 = shift;
my $ARGV1 = shift;
my $ARGV2 = shift;

open ( TOKENS, $ARGV0 ) || die "can't open token file: $!";
my %tokens;

while ( defined (my $line = <TOKENS>) )
{
chomp($line);
my @token = split(' ',$line);
unless ( defined ($token[1]) )
{
$token[1] = "XML_".$token[0];
$token[1] =~ tr/\-\.\:/___/;
$token[1] =~ s/\+/PLUS/g;
$token[1] =~ s/\-/MINUS/g;
}

$tokens{$token[0]} = $token[1];
}
close ( TOKENS );

open ( HXX, ">$ARGV1" ) or die "can't open tokens.hxx file: $!";
open ( GPERF, ">$ARGV2" ) or die "can't open tokens.gperf file: $!";

print ( GPERF "%language=C++\n" );
print ( GPERF "%global-table\n" );
print ( GPERF "%null-strings\n" );
print ( GPERF "%struct-type\n" );
print ( GPERF "struct xmltoken\n" );
print ( GPERF "{\n" );
print ( GPERF " const sal_Char *name; sal_Int32 nToken; \n" );
print ( GPERF "};\n" );
print ( GPERF "%%\n" );

print ( HXX "#ifndef _TOKEN_HXX_\n" );
print ( HXX "#define _TOKEN_HXX_\n\n" );
print ( HXX "#ifndef _SAL_TYPES_H_\n" );
print ( HXX "#include <sal/types.h>\n" );
print ( HXX "#endif\n\n" );

$i = 0;
foreach( sort(keys(%tokens)) )
{
print( HXX "const sal_Int32 $tokens{$_} = $i;\n" );
print( GPERF "$_,$tokens{$_}\n" );
$i++;
}
print ( GPERF "%%\n" );
print ( HXX "const sal_Int32 XML_TOKEN_COUNT = $i;\n" );
print ( HXX "#endif\n" );
close ( HXX );
close ( GPERF );
</pre>

The generated .hxx file has the following format

<pre>
#ifndef _TOKEN_HXX_
#define _TOKEN_HXX_

#ifndef _SAL_TYPES_H_
#include <sal/types.h>
#endif

const sal_Int32 User = 0:
const sal_Int32 Admin = 1;
const sal_Int32 Name = 2;
const sal_Int32 Login = 3;
const sal_Int32 XML_TOKEN_COUNT = 4;
</pre>

This can be automated by adding the following at the end of your makefile.mk

<pre>
$(INCCOM)$/tokens.hxx $(MISC)$/tokens.gperf : tokens.txt gentoken.pl
$(PERL) gentoken.pl tokens.txt $(INCCOM)$/tokens.hxx $(MISC)$/tokens.gperf

$(INCCOM)$/tokens.cxx : $(MISC)$/tokens.gperf
gperf --compare-strncmp --output-file=$(MISC)$/_tokens.cxx $(MISC)$/tokens.gperf
$(TYPE) $(MISC)$/_tokens.cxx | $(SED) -e "s/(char\*)0/(char\*)0, 0/g" >$(INCCOM)$/tokens.cxx

$(SLO)$/tokenmap.obj : $(INCCOM)$/tokens.cxx $(INCCOM)$/tokens.hxx

$(INCCOM)$/tokens.gperf : $(INCCOM)$/tokens.hxx
</pre>

This automatically creates the tokens.hxx and a tokens.cxx in your platforms include folder of your project.

The following code uses the tokens.cxx generated by gperf to implement a XFastTokenHandler

<pre>

#include <com/sun/star/xml/sax/XFastTokenHandler.hpp>
#include <com/sun/star/xml/sax/FastToken.hpp>
#include <cppuhelper/implbase1.hxx>

#include "tokens.hxx"

#include "tokens.cxx" // this also includes the c++ code created from gperf

using ::rtl::OUString;
using ::osl::Mutex;
using ::osl::MutexGuard;
using namespace ::com::sun::star::xml::sax;
using namespace ::com::sun::star::uno;

class FastTokenHandler : public ::cppu::WeakImplHelper1< XFastTokenHandler >
{
public:
virtual sal_Int32 SAL_CALL getToken( const OUString& Identifier ) throw (RuntimeException);
virtual OUString SAL_CALL getIdentifier( sal_Int32 Token ) throw (RuntimeException);
virtual sal_Int32 SAL_CALL getTokenFromUTF8( const Sequence< sal_Int8 >& Identifier ) throw (RuntimeException);
};

Mutex& getTokenMutex()
{
static Mutex aMutex;
return aMutex;
}

sal_Int32 FastTokenHandler::getToken( const OUString& Identifier ) throw (RuntimeException)
{
MutexGuard guard( getTokenMutex() );

OString aUTF8( Identifier.getStr(), Identifier.getLength(), RTL_TEXTENCODING_UTF8 );

struct xmltoken * t = Perfect_Hash::in_word_set( aUTF8, aUTF8.getLength() );
if( t )
return t->nToken;
else
return FastToken::DONTKNOW;
}

OUString FastTokenHandler::getIdentifier( sal_Int32 nToken ) throw (RuntimeException)
{
MutexGuard guard( getTokenMutex() );

if( nToken >= XML_TOKEN_COUNT )
return OUString();

static OUString aTokens[XML_TOKEN_COUNT];

if( aTokens[nToken].getLength() == 0 )
aTokens[nToken] = OUString::createFromAscii(wordlist[nToken].name);

return aTokens[nToken];
}

sal_Int32 FastTokenHandler::getTokenFromUTF8( const Sequence< sal_Int8 >& Identifier ) throw (RuntimeException)
{
MutexGuard guard( getTokenMutex() );

struct xmltoken * t = Perfect_Hash::in_word_set((const char*)Identifier.getConstArray(), Identifier.getLength());
if( t )
return t->nToken;
else
return FastToken::DONTKNOW;
}

</pre>
[[Category:API]]

Mac OS X Implementing HIView

2010-05-28T00:07:53Z

Newacct:

== Contributors ==

Eric Bachard[[http://wiki.services.openoffice.org/wiki/User:Ericb ericb]]

Sébastien Plisson [[http://wiki.services.openoffice.org/wiki/User:Plipli plipli]]

== Introduction ==

'''[DRAFT] : means, not yet working, work in progress ... '''

HIObject is a common base class for all user interface objects and all menus, windows, controls, toolbars, and so on, are subclasses of HIObject.

HIView is an object-oriented view system subclassed from HIObject. All controls are implemented as HIView objects ("views"). You can easily subclass HIView classes, making it easy to implement custom controls. Over time the HIView API will replace the current Control Manager. See [[http://developer.apple.com/documentation/Carbon/Conceptual/HandlingWindowsControls/hitb-wind_cont_tasks/chapter_3_section_9.html HIView intro]]

The main idea behind HIView is to superpose plans, to create any view, using compositing possibilities of Quartz Graphical Engine.

The final result is the superposition of all plans, following simple rules like :

- The last plan is always drawn on the previous one ;
- Some plans can be declared visible, or not, very easily.

This page is part of [[http://wiki.services.openoffice.org/wiki/Mac_OS_X_Porting_-_Native_Controls Native Controls Implementation]] and the objective is to use HIView for HIComboboxes or other HI* controls.

Our objective is to bind vcl controls with HI* controls, from Carbon API.

e.g. : implement HICombobox as one control only.

The generic implementation, under tests (and not fully working), uses :

'''In progress :''' 
- plipli : '''HIFramework''' integration : compiled, to be cleaned up before testing delivery to mac@porting ;
- ericb/ismael : salnativewidget - create and bind '''native controls''' (HIViews) (ericb) and '''HIWindow''' (ismael);

Note : we "or"- ed kWindowCompositingAttribute in nWindowAttributes, to see compositing effects.
[FIXME] : investigate, because use this attribute causes refresh issues

== HIFramework integration and benefits ==
--[[User:Plipli|Plipli]] 15:00, 25 April 2007 (CEST)

* '''''Origin''''' : Issued from Apple samples

* '''''Pros''''' :
- use recent API code, 
- given with many helpers and set/getters to manage data and events 
- easily adaptable to use new services coming with Leopard (MacOSX 0.5) 
- up/down compatibility with different MacOSX versions 
- hiobject registering system : low couplage with the utility classes of HIFramework 

* '''''Cons''''' :
- ?? too nice to be true :-)

* '''''Step by step''''' :
'''1''' - When any HIObject is created in salframe/salnativewidget (AquaSalFrame / AquaSalGraphics) it will be
registered to HIFramework base classes ; 
'''2a''' - Being registered gives this instance of HIView/HIWindow access to helpers/setters/getters methods ; 
'''2b''' - Event handling is highly centralized/factored : create, initialize, draw... ; 
'''3''' - Almost all possible data / events is covered by HIFramework and will be easily used, as new controls are implemented in salnativewidget ; 

* '''''Conclusion''''' :
- Let's clean it, test it and enjoy fastest implementation of Aqua native controls !! (GsoC fun ;-)

== Technical principles ==

1) OO ask to VCL / native implementation code to draw controls (ie DrawNativeControl) or images or text

2) For controls, native implementation code create objects but do not draw them
For images and text, native code draw objects to context (from QDBegin) or context from HiView event

3) When HIView events are received by event handler, especially kEventControlDraw, native code should draw controls to context given by the event

4) Native code call needsDisplay functions to tell Quartz which zone to update

== Current code implementation==

===Events for HIView ===

Two sorts of events are needed:

*for objects (ClasskEventClassHIObject ) :

<pre>kEventHIObjectConstruct

kEventHIObjectInitialize

kEventHIObjectDestruct</pre>

*for controls themselves ( Class kEventClassControl ) :

<pre>kEventControlDraw

kEventControlInitialize

kEventControlHitTest

kEventControlGetPartRegion

</pre>

Current implementation : see vcl/aqua/aquavclevents.hxx for more informations about the syntax.

===Install Event Handler ===

Now we have to install event Handler, inside AquaSalFrame::CreateNewSystemWindow() :
<pre>

InstallEventHandler (
GetControlEventTarget (mhView),
NewEventHandlerUPP (HandleHIViewEvent),
GetEventTypeCount (cHIViewEvent),
cHIViewEvent,
(void*)mhView, // note the use of the pointer
NULL
);

</pre>

=== The HI* Event Handler ===

The Handler is OSStatus type, and is used when events are detected.

e.g. : we created HandleHIViewEvent()

using GetEventParameter, itself using the parameters described in Apple documentation.

Code sample :
<pre>
OSStatus HandleHIViewEvent(EventHandlerCallRef inHandlerCallRef, EventRef inEvent, void* inUserData)
{
//lock
ImplSalYieldMutexAcquire();

OSStatus status = noErr;

// we use mrContext, global and seen from everywhere
CGContextRef mrContext;

// create HIRect, containing the control bounds ( in local coordinates)
HIRect bounds;

status = GetEventParameter (inEvent,
kEventParamCGContextRef,
typeCGContextRef,
NULL,
sizeof (CGContextRef),
NULL,
&mrContext);

// not used, but useful
//require_noerr(status, CantGetGraphicsContext); // 2

// We need to know the bounds containing the current control
HIViewGetBounds ((HIViewRef) inUserData, &bounds);

// not used, but useful
//require_noerr(status, CantGetBoundingRectangle);

// unlock
ImplSalYieldMutexRelease();

return status;
}
</pre>

===HIView use in AquaSalFrame::CreateNewSystemWindow() ===

Code sample :

<pre>

// TEST HIVIew part
// Set mrContentView with HIView Content ViewRef

HIRect myViewRect;
myViewRect.origin.x = aContentRect.left;
myViewRect.origin.y = aContentRect.right;
myViewRect.size.width = aContentRect.right-aContentRect.left;
myViewRect.size.height = aContentRect.bottom-aContentRect.top;
OSStatus errval;
errval = HIViewFindByID(HIViewGetRoot(mrWindow), kHIViewWindowContentID, &mrContentView);

// make the view visible
HIViewSetVisible (mrContentView, true);

// set the frame
HIViewSetFrame (mrContentView, &myViewRect);

// Activate content view and children
HIViewSetActivated (mrContentView,true);

</pre>

=== Controls ===

[FIXME]

Example : HICombobox

-> code located in vcl/aqua/source/gdi/salnativewidgets.cxx , where all NWF are defined

1) declare CTRL_COMBOBOX control as "true" in isNativeControlSupported()

2) get the control region in getNativeControlRegion()

3) add CTRL_COMBOBOX case in drawNativeControl()

Code sample for the last part (Warning : not yet working !! ) :

<pre>
switch( nType )
{

case CTRL_COMBOBOX:
if ( ( nPart==PART_BUTTON_DOWN) || (nPart==PART_SUB_EDIT) || (nPart==PART_ENTIRE_CONTROL) || (nPart==HAS_BACKGROUND_TEXTURE))

.... (other code )

HIViewRef myCombo;

HIRect rc2;

rc2.origin.x = rControlRegion.GetBoundRect().Left();
rc2.origin.y = rControlRegion.GetBoundRect().Top();
rc2.size.width = rControlRegion.GetBoundRect().GetWidth();
rc2.size.height = rControlRegion.GetBoundRect().GetHeight();

HIComboBoxCreate ( &rc2 , NULL, NULL, NULL, kHIComboBoxStandardAttributes, &myCombo);

HIViewSetVisible ( myCombo, true);
HIViewAddSubview (mrView, myCombo);

HIViewSetNeedsDisplay (myCombo, true);

printf ("rc2.origin.x %.0f \n rc2.origin.y %.0f \n rc2.size.width %.0f \n rc2.size.height %.0f \n",
rc2.origin.x, rc2.origin.y, rc2.size.width , rc2.size.height );

//HIViewSetActivated (myCombo,true);

..... (other code )
</pre>

== Usefull Links ==

=== References ===

[[http://developer.apple.com/documentation/Carbon/Conceptual/HandlingWindowsControls/hitb-wind_cont_tasks/chapter_3_section_9.html Introducing HIView]]

OverView : [[http://developer.apple.com/carbon/HIToolbox_feature.html HIToolbox]]

HIVIew : [[http://developer.apple.com/documentation/Carbon/Reference/HIViewReference/Reference/reference.html reference]] [[http://developer.apple.com/documentation/Carbon/Reference/HIViewReference/HIViewReference.pdf or .pdf format]]

[[http://developer.apple.com/documentation/Carbon/Conceptual/Upgrading_HIToolbox/index.html Upgrading to HIToolbox]]

===Code sample ===

Build a big toy with all controls included : [http://developer.apple.com/samplecode/AppearanceSampleUpdated/listing575.html All controls + code around]

High Level Toolbox, HIServices Release Notes : [http://developer.apple.com/releasenotes/Carbon/RN-HIToolbox/ HIToolbox]

[[Category:Porting]]
[[Category:MacOSX]]
[[Category:Aqua]]

Qa/Testtool WinXP

2010-05-27T09:46:42Z

Newacct:

[[Category:Quality Assurance]]

This page is intended to help the Windows users to use the Testtool. The info on this page is for Windows XP, but it's useful for most Windows versions.
Please, change 'ja' for your ISO language code when needed.
Also take into account this info is up to version 2.1.

= How to obtain OS =
You've to have an Windows license, a install disc and ensure the your license allows you to install it on a virtual machine.

= Setup =

As the releases tests takes about 15 hours and use the mouse, keyboard or an OpenOffice.org instance can't be used, most people would prefer an alternative way to running the tests in the main box. The common method for Windows is:
* Install the OS inside a virtual machine

== Installation of OS inside the Vmware player ==
You can use the virtual machine you want, but Vmware player is free and is a lot faster than Qemu, so we recommend using Qemu to setup the virtual machine and Vmware player to running it.

The basic steps are:
* creation of HDD image
qemu-img create -f vmdk winXPja.vmdk 10G
:You should have qemu-img on your OS path or run this command in the directory where Qemu is installed.

* creation of winXPja.vmx
:Save the following section as the FC6.vmx file in the same folder in which the image file is located.
config.version = "8"
virtualHW.version = "3"

displayName = "Windows XP SP2 Japanese"
guestOS = "winXPPro"
memsize = "256"
usb.present = "FALSE"
floppy0.present = "FALSE"
sound.present = "TRUE"
sound.virtualdev = "es1371"

ethernet0.present = "TRUE"
ethernet0.addressType = "generated"
ethernet0.generatedAddress = ""
ethernet0.generatedAddressOffset = "0"
ethernet0.connectionType = "bridged"

ide0:0.present = "TRUE"
ide0:0.fileName = "winXPja.vmdk"
ide0:0.deviceType = "disk"
ide0:0.startConnected = "TRUE"
ide0:0.redo = ""

ide1:0.present = "TRUE"
ide1:0.fileName = "auto detect"
ide1:0.deviceType = "cdrom-raw"

ide1:1.present = "TRUE"
ide1:1.fileName = "auto detect"
ide1:1.deviceType = "cdrom-raw"

* follow instruction of p.37 of Guest OS installation guide
http://www.vmware.com/pdf/GuestOS_guide.pdf
http://www.vmware.com/support/pubs/player_pubs.html
I allocated Y: for iso image mount drive at the host OS, thus this is 2nd CD/DVD-ROM drive.
So, to boot Win XP Pro install program from CD-ROM image via daemon tool,
I disconnected 1st CD-ROM at boot time when the vmware player started. Otherwise
winXP Pro installation program doesn't boot.

* installation of vmware tools
Get windows.iso from vmware server, mount windows.iso via daemon tool,
and install.

= Update the OS =
* Activation.
* via Windows update, updated to up to date Windows XP SP2.

= Some miscellaneous settings =
We should not move mouse during this test. Screensaver is also harmful, activate sleep mode is very harmful.

* Show all files and folders.
o Translated from Japanese (may be wrong :)
Explorer->Tool->Folder option ->show ->files and folders->
Not show extension that is registered.
* Show the extensions even they are registered
o Translated from Japanese (may be wrong :)
Explorer->Tool->Folder option ->show ->files and folders->
check Show All files and folders
* Screen saver has been disabled.
o Translated from Japanese (may be wrong :)
Control Panel -> Display -> Choose Screen saver->
->Screen saver ->(none)
* Energy saving
All set to (none)
* Disable the error report
Control Panel -> System -> Advanced -> Error report
You might to "Enable error report" and uncheck "Programs", or to
"Disable error report".
Remember to enable later if you like it.

= Download and install =
* OOo 2.1RC2
http://oootranslation.services.openoffice.org/pub/OpenOffice.org/2.1.0rc2/OOo_2.1.0rc2_20061130_Win32Intel_install_ja_wJRE.exe
* QA tool
ftp://ftp.ooodev.org/pub/qa/qatesttool_ooo201_20062311.tgz

== Verification of MD5 sums ==
You might to download a MD5 sum checktool from [http://www.etree.org/md5com.html] and to install it.
* run a MD5 check against the downloaded file
md5sum OOo_2.1.0rc2_20061130_Win32Intel_install_ja_wJRE.exe
* check the MD5 sum
:compare with the one from [http://www.openoffice.org/servlets/ReadMsg?list=releases&msgNo=10261]
* Check the qatesttool_ooo201_20062311.tgz MD5 sum
:compare with the one from [http://qa.openoffice.org/servlets/ReadMsg?list=dev&msgNo=7328]

% md5sum qatesttool_ooo201_20062311.tgz
d43d1ed59ea7bd10330be1276d79c6b1 qatesttool_ooo201_20062311.tgz

== Installation ==
It's done as usual. You may want to follow instruction from official installation guide. 
(If wrong, raise an issue!) 
[http://documentation.openoffice.org/setup_guide2/2.x/en/SETUP_GUIDE_A4.pdf English] 
[http://documentation.openoffice.org/setup_guide2/2.x/ja/SETUP_GUIDE_A4J.pdf Japanese] 

== QA tools ==
* C:\Document and Settings\<User Name>\Application Data\testtool.ini has been created like following:
[Misc]
ServerTimeout=100000
StopOnSyntaxError=0
AutoReload=0
AutoSave=0
CurrentProfile=_profile_testtool
ScriptFontName=Courier
ScriptFontStyle=normal
ScriptFontSize=12

[Path]
BaseDir=
LogBaseDir=
HIDDir=

[GUI Platform]
Current=501
All=501

[WinGeom]
WinParams=228,124,802,620;1;0,0,0,0;

[OooProgramDir]
Current=C:\Program Files\OpenOffice.org 2.1
All=C:\Program Files\OpenOffice.org 2.1

[_profile_testtool]
LogBaseDir=C:\work\qa\qatesttool\errorlog
BaseDir=C:\work\qa\qatesttool
HIDDir=C:\work\qa\qatesttool\global\hid
AutoReload=0
AutoSave=0
StopOnSyntaxError=0
*.bas=C:\work\qa\qatesttool\framework\first

[LRU]
MaxLRU=4
LRU1=C:\work\qa\qatesttool\framework\first\first.bas

[Communication]
Host=localhost
TTPort=12479
UnoPort=10241

[Crashreporter]
UseProxy=false
ProxyServer=none
ProxyPort=8080
AllowContact=false
ReturnAddress=

[Misc]
ServerTimeout=4500
StopOnSyntaxError=0
AutoReload=0
AutoSave=0
CurrentProfile=_profile_testtool
ScriptFontName=Courier
ScriptFontStyle=normal
ScriptFontSize=12

* Extract qatesttool_ooo201_20062311.tgz at C:\work\qa so that tree become:
C:\work\work\qa\testtool ...

* Apply following patch for ooo_releasetests.bat

C:\work\qa\qatesttool\script\win32\ooo_relesetests.bat
--- qa/qatesttool/script/win32/ooo_releasetests.bat Mon Oct 16 20:22:45 2006
+++ qa/qatesttool/script/win32/ooo_releasetests.bat Sun May 28 19:34:33 2006
@@ -59,10 +59,10 @@

rem set location of TestTool
rem (full path including executable 'testtool')
-set tool="C:\qatesttool\bin\win32\testtool.exe"
+set tool="C:\Program Files\OpenOffice.org 2.1\program\testtool.exe"

rem set path to directory which contains directory 'qatesttool'
-set work="C:\qatesttool\scripts"
+set work="C:\work\qa"

%tool% -run %work%\qatesttool\framework\first\first.bas
%tool% -run %work%\qatesttool\global\tools\closeoffice.bas

= QAtest =

* Make sure that quick start is not active (you can verify by no seagull small icon at the right bottom of your screen)
* removed C:\work\qa\qatesttool\errorlogs\*res (if present)
* removed C:\Document and Settings\<UserName>\Application Data\OpenOffice.org2 (if present)
* Double click C:\work\qa\qatesttool\script\win32\ooo_releasetests.bat

I recived following message from Windows XP:
Important warning of Windows Security.
To protect this computer, Windows firewall blocks some
functions. Do you block this program?''
Name(N): OpenOffice.org 2.1
Producer(P): OpenOffice.org

I ignored this massage...during test.

= Summary =

Check the result files for errors and upload the *res files to the IssueTracker.
If any found, try to reproduce manually and file bugs if needed.

SDKCppLanguage

2010-05-17T21:49:59Z

Newacct:

{{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 “<OpenOffice.org1.1_SDK>/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 <OpenOffice.org1.1_SDK>
./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() { printf( "constructed\n" ); }
~MyOWeakObject() { printf( "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();

printf( "before release\n" );

// release it, refcount drops to zero
p->release();

printf( "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]]

PyUNOServer

2010-05-15T05:49:10Z

Newacct:

[[image:Py-uno_128.png|right|PyUNO Logo]]
The PyUNOServer is a script that works as an XML server for OpenOffice.org Calc where it can exchange data through XML calls. This means that can get data from other apps that are XML compliant. You can download the script from [http://es.openoffice.org/files/documents/73/2929/pyUnoServer.tar.gz this mirror] since the original site seems to be down.

The zip file contains 3 files:
* '''PyUNOServerV2.py''' - The Python Script
* '''PyUNOServerV2.pyc''' - compiled version
* '''PyUNOServer.sh2''' - the script to conect to the service

The script have just 1 script called '''PyUNOServerV2.py''' however there is a faster, bytecode-compiled script. It also includes a bash script which loads the path to the openoffice.org application.

'''NOTE: This script will work on just certain distros since the location of OpenOffice.org might vary. We recomend to load the path manually.'''

This script uses the following libraries:

* '''OS''' - This module provides a more portable way of using operating system dependent functionality than importing a operating system dependent built-in module like posix or nt.
* '''UNO''' - Python UNO implementation module, this can used by python 2.3.4 '''only''' which is the python provided within openoffice.org. It provides all the interfaces from OpenOffice.org into python.
* '''SYS''' - This module provides access to some variables used or maintained by the interpreter and to functions that interact strongly with the interpreter. It is always available.
* '''time''' - This module provides various time-related functions. It is always available, but not all functions are available on all platforms. Most of the functions defined in this module call platform C library functions with the same name. It may sometimes be helpful to consult the platform documentation, because the semantics of these functions varies among platforms.
* '''logging''' - Logging is performed by calling methods on instances of the Logger class (hereafter called loggers). Each instance has a name, and they are conceptually arranged in a name space hierarchy using dots (periods) as separators.
* '''urllib''' - This module provides a high-level interface for fetching data across the World Wide Web. In particular, the urlopen() function is similar to the built-in function open(), but accepts Universal Resource Locators (URLs) instead of filenames. Some restrictions apply -- it can only open URLs for reading, and no seek operations are available.
* '''SimpleXMLRPCServer''' - The SimpleXMLRPCServer module provides a basic server framework for XML-RPC servers written in Python. Servers can either be free standing, using SimpleXMLRPCServer, or embedded in a CGI environment, using CGIXMLRPCRequestHandler.

<source lang=python>
# -*- coding: iso-8859-1 -*-
#
# pyUnoServer - version 2.0
from SimpleXMLRPCServer import SimpleXMLRPCServer, SimpleXMLRPCRequestHandler
import os
import uno
import sys
import time
import logging
import urllib

class PyUNOServer(SimpleXMLRPCServer):

def _dispatch(self, method, params):

try:
func = getattr(self, '' + method)
except:
self.logger.error("El Metodo '"+method+"' no esta soportado!")
raise Exception('method "%s" is not supported' % method)
else:
try:
ret = func(*params)
self.logger.info("Llamada: %s%s | Retorno: %s" % (method, params, ret))
return ret
except:
self.logger.info("Llamada: %s%s" % (method, params))
self.logger.error("Error: %s:%s" % sys.exc_info()[:2])

def init(self):
"""
This method starts an Openoffice session and initializes the XMLRPC server
"""

# Generate some useful constants
self.EMPTY = uno.Enum("com.sun.star.table.CellContentType", "EMPTY")
self.TEXT = uno.Enum("com.sun.star.table.CellContentType", "TEXT")
self.FORMULA = uno.Enum("com.sun.star.table.CellContentType", "FORMULA")
self.VALUE = uno.Enum("com.sun.star.table.CellContentType", "VALUE")

# Generate a Logger
self.logger = logging.getLogger('pyUnoServer')
hdlr = logging.FileHandler('./pyUnoServer.log')
formatter = logging.Formatter('%(asctime)s %(levelname)s -- %(message)s')
hdlr.setFormatter(formatter)
self.logger.addHandler(hdlr)
self.logger.setLevel(logging.INFO)

self.sessions = []
self.sessionSerial = 0

# Start Calc and grep the PID
self.PID = os.spawnlp(os.P_NOWAIT,"/usr/bin/oocalc","","-accept=socket,host=localhost,port=2002;urp;")

self.logger.info("OOCalc Iniciado con el PID %d" % self.PID)

while 1:
try:
localContext = uno.getComponentContext()
resolver = localContext.ServiceManager.createInstanceWithContext("com.sun.star.bridge.UnoUrlResolver", localContext )
smgr = resolver.resolve( "uno:socket,host=localhost,port=2002;urp;StarOffice.ServiceManager" )
remoteContext = smgr.getPropertyValue( "DefaultContext" )
self.desktop = smgr.createInstanceWithContext( "com.sun.star.frame.Desktop",remoteContext)
self.logger.info("Sistema conectado al socket de UNO")
break
except:
time.sleep(0.5)

def openSession(self, session):
"""
This method opens a new session.
Sample usage from PHP:
- $sessionString is your a session ID provided by your program):

$openSession = array( new XML_RPC_VALUE($sessionString, "string"));
$sessionID = queryXMLRPC($client, "openSession", $openSession);
return $sessionID;
"""

for i,x in enumerate(self.sessions):
if x[0] == session:
currentSerial = i
break
else:
self.sessions.append([session,[]])
currentSerial = len(self.sessions)-1

return currentSerial

def getSessions(self):
return self.sessions

def openBook(self, session, bookPath):
"""
This method opens a new Openoffice spreadsheet book.
Sample usage from PHP:
- $sessionID is the session's ID returned by openSession()
- $path is the path to the book in the server's filesystem

$openBookQuery = array( new XML_RPC_VALUE($sessionID, "int"), new XML_RPC_VALUE($path,"string") );
$bookID = queryXMLRPC($client, "openBook", $openBookQuery);
return $bookID;
"""

currentSerial = session
bookPath = bookPath.strip()
print bookPath

exists = os.path.exists(bookPath)
if exists == False:
raise Exception('El libro %s no existe', bookPath)
else:
self.logger.info("se ha encontrado el libro!")

currentBook = -1

for i, book in enumerate(self.sessions[currentSerial][1]):
try:

bookname = book[0]
bookhandler = book[1]
bookmodtime = book[2]

if bookname == bookPath:
modtime = os.path.getmtime(bookPath)
if modtime > bookmodtime:
book[1].dispose()
self.sessions[currentSerial][1].remove(book)
else:
currentBook = i
break
except:
self.logger.error("El libro "+currentBook+" no existe!")

if currentBook < 0:
handler = self.desktop.loadComponentFromURL( "file://" + bookPath ,"_blank",0,())

if handler == None:
raise Exception('El libro no existe o tiene caracteres extraños...')

modtime = os.path.getmtime(bookPath)

estruct = [bookPath,handler,modtime]
self.sessions[currentSerial][1].append(estruct)
currentBook = len(self.sessions[currentSerial][1])-1

return currentBook

def closeBook(self, sessionID, bookID):

books = self.sessions[sessionID][1]

# Close the document. It doesn't look very elegant but thats the way is documented.
books[bookID][1].dispose()
self.sessions[sessionID][1].remove(books[bookID])

return 1

def getBookSheets(self, sessionID, bookID):
"""
This method return an array with the book's worksheets.
Sample usage from PHP:
- $sessionID is the session's ID returned by openSession()
- $bookID is the book's ID returned by openBook()

$sheetsQuery = array( new XML_RPC_VALUE($sessionID, "int"), new XML_RPC_VALUE($bookID, "int") );
$sheets = queryXMLRPC($client, "getBookSheets" , $sheetsQuery);
return $sheets;
"""

sheets = self.sessions[sessionID][1][bookID][1].getSheets().createEnumeration()

container = []
while sheets.hasMoreElements():
currentSheet = sheets.nextElement()
container.append(currentSheet.getName().encode("UTF-8"))

return container

def getCellValue (self,sheet,x,y):

cell = sheet.getCellByPosition(x,y)
cellType = cell.getType()

if cellType == self.TEXT :
data = cell.getString().encode("UTF-8")
if data == None:
return ""
return data.encode("UTF-8")

if cellType == self.FORMULA or cellType == self.VALUE :
data = cell.getValue()
if data == None:
return 0
return cell.getValue()

if cellType == self.EMPTY :
return ""

def getCell(self, session, book, sheet, x, y):
"""
This method returns the content of a cell.
Sample usage from PHP:
- $sessionID is the session's ID returned by openSession()
- $bookID is the book's ID returned by openBook()
- $sheet is the sheet's ID as returned by getBookSheets()

$query = array(
new XML_RPC_Value($sessionID, "int"),
new XML_RPC_VALUE($bookID, "int"),
new XML_RPC_VALUE($sheet, "int"),
new XML_RPC_Value($x, "int"),
new XML_RPC_Value($y, "string")
);

$result = queryXMLRPC($client, "getCell", $query);
return $result;
"""

sheetref = self.sessions[session][1][book][1].getSheets().getByIndex(sheet)
valor = self.getCellValue(sheetref,x,y)
return valor

def setCell(self,session,book,sheet,x,y,value):
"""
This method sets the content of a cell.
Sample usage from PHP:
- $sessionID is the session's ID returned by openSession()
- $bookID is the book's ID returned by openBook()
- $sheet is the sheet's ID as returned by getBookSheets()

$query = array(
new XML_RPC_Value($sessionID, "int"),
new XML_RPC_VALUE($bookID, "int"),
new XML_RPC_VALUE($sheet, "int"),
new XML_RPC_Value($x, "int"),
new XML_RPC_Value($y, "int"),
new XML_RPC_Value($value, "string")
);

$result = queryXMLRPC($client, "setCell", $query);
return $result;
"""

bookObject = self.sessions[session][1][book][1]
cell = bookObject.getSheets().getByIndex(sheet).getCellByPosition(x,y)
cell.setValue(value)
return 1

#what will change? mmm...
def massiveSetCell(self, data):
for valores in data:
session,sheetid,x,y,valor = valores.split("|")
code = self.setCell(self.trim(session),self.trim(sheetid),self.trim(x),self.trim(y),valor)
if code < 0:
return code
return 1

def getSheetPreview(self,session,book,sheet):

sheet = self.sessions[session][1][book][1].getSheets().getByIndex(sheet)
range = sheet.getCellRangeByPosition(0,0,8,23).getDataArray()
return range

def trim(self, cadena):
return cadena.strip()

server = PyUNOServer(("localhost", 8000))

server.init()
server.logger.info("Servicio Inicializado...")

try:
server.serve_forever()
except KeyboardInterrupt:
server.logger.info("Cerrando el socket...")
server.server_close()
os.kill(server.PID,1)
server.logger.info("Socket cerrado.")
</source>

==startPyUnoServer.sh2==
<source lang=bash>
#!/bin/bash
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib/openoffice/program/
export PYTHONPATH=$PYTHONPATH:/usr/lib/openoffice/program
export DISPLAY=localhost:1
echo "Logging en pyUnoServer.log"
python pyUnoServerV2.py
echo "Ciao!"
</source>

[[Category:Python]][[Category:Uno]]

Python container components

2010-05-12T07:15:52Z

Newacct:

===Python container components===

I have been dabbling with creating components in Python. This message is intended as an update on what I have learned and am experimenting with.

As a first experiment, here is a single python component program which implements two services.

The two new services are....

<pre>name.dannyBrewer.util.IndexContainer
name.dannyBrewer.util.NameContainer </pre>

Here is how you install the new component.
* Copy the text of the following python source code.
* Put it into a file named "DannyComponentTest2004052217.py"
* Put the file DannyComponentTest2004052217.py into the uno_components folder of your "user" folder.

The user folder on Windows is probably the folder named "user" under your OOo installation.
The user folder on Linux is contained within a folder in your home directory with a name like OpenOffice.org1.1.1.
(Note on Linux, be sure that when you copy the python program that it has no carriage returns, but instead has unix linefeeds. Otherwise the component will not install properly!)

(New edit 2005-03-28: It may in fact be important now on ALL platforms to make sure that the ".py" file of python source has its line endings separated by linefeeds only with NO carriage returns!)

* Be sure that OOo is NOT running.
* Run the command "pkgchk" in your OOo\programs folder.

To uninstall do this....
* Remove the DannyComponentTest2004052217.py file from your uno_components folder.
* Be sure that OOo is NOT running.
* Run the pkgchk command.

After installing the component, you have two new data structure services that can be instantiated from any language which can access UNO components. For instance, in OOo Basic, you can simply do...
oItems = createUnoService( "name.dannyBrewer.util.IndexContainer" )

<pre>import unohelper

g_ImplementationHelper = unohelper.ImplementationHelper()

##################################################################
class DannysUnoBaseClass:
cServiceName = ""
tServiceNames = ( cServiceName, )
# stuff to support the XTypeProvider interface.
tInterfaceTypes = (
uno.getTypeByName( "com.sun.star.lang.XServiceName" ),
uno.getTypeByName( "com.sun.star.lang.XServiceInfo" ),
uno.getTypeByName( "com.sun.star.lang.XTypeProvider" ),
)
uuid = uno.generateUuid()

# The component must have a ctor with the component context as argument.
def __init__( self, oContext ):
self.DannysUnoBaseClass_init( oContext )

def DannysUnoBaseClass_init( self, oContext ):
self.oContext = oContext

self.oCoreReflection = None
self.StarDesktop = None
self.getDesktop()

#----------------------------------------
# Danny's stuff to make programming less convenient.
#----------------------------------------

def getServiceManager( self ):
"""Get the ServiceManager from the running OpenOffice.org.
"""
return self.oContext.ServiceManager

def createUnoService( self, cClass ):
"""A handy way to create a global objects within the running OOo.
"""
oServiceManager = self.getServiceManager()
oObj = oServiceManager.createInstance( cClass )
return oObj

def getDesktop( self ):
"""An easy way to obtain the Desktop object from a running OOo.
"""
if self.StarDesktop == None:
self.StarDesktop = self.createUnoService( "com.sun.star.frame.Desktop" )
return self.StarDesktop

def getCoreReflection( self ):
if self.oCoreReflection == None:
self.oCoreReflection = self.createUnoService( "com.sun.star.reflection.CoreReflection" )
return oCoreReflection

def createUnoStruct( self, cTypeName ):
"""Create a UNO struct and return it.
"""
oCoreReflection = self.getCoreReflection()

# Get the IDL class for the type name
oXIdlClass = oCoreReflection.forName( cTypeName )

# Create the struct.
oReturnValue, oStruct = oXIdlClass.createObject( None )

return oStruct

def makePropertyValue( self, cName=None, uValue=None, nHandle=None, nState=None ):
"""Create a com.sun.star.beans.PropertyValue struct and return it.
"""
oPropertyValue = self.createUnoStruct( "com.sun.star.beans.PropertyValue" )

if cName != None:
oPropertyValue.Name = cName
if uValue != None:
oPropertyValue.Value = uValue
if nHandle != None:
oPropertyValue.Handle = nHandle
if nState != None:
oPropertyValue.State = nState

return oPropertyValue

#----------------------------------------
# Interface: XServiceName
#----------------------------------------

# string
# getServiceName();
def getServiceName( self ):
return self.cServiceName

#----------------------------------------
# Interface: XServiceInfo
#----------------------------------------

# string
# getImplementationName();
def getImplementationName( self ):
return self.cServiceName

# boolean
# supportsService( [in] string ServiceName );
def supportsService( self, cServiceName ):
return cServiceName in self.getSupportedServiceNames()

# sequence< string >
# getSupportedServiceNames();
def getSupportedServiceNames( self ):
return self.tServiceNames

#----------------------------------------
# Interface: XTypeProvider
#----------------------------------------

# sequence< type >
# getTypes();
def getTypes( self ):
#if self.tInterfaceTypes == None:
# self.tInterfaceTypes = ()
# for cTypeName in self.tInterfaces:
# self.tInterfaceTypes += ( uno.getTypeByName( cTypeName ), )
return self.tInterfaceTypes

# sequence< byte >
# getImplementationId();
def getImplementationId( self ):
return self.uuid

##################################################################
from com.sun.star.lang import IndexOutOfBoundsException

class IndexContainer( DannysUnoBaseClass ):
cServiceName = "name.dannyBrewer.util.IndexContainer"
tServiceNames = ( cServiceName, )
tInterfaceTypes = DannysUnoBaseClass.tInterfaceTypes + (
uno.getTypeByName( "com.sun.star.container.XIndexContainer" ),
uno.getTypeByName( "com.sun.star.container.XIndexReplace" ),
uno.getTypeByName( "com.sun.star.container.XIndexAccess" ),
uno.getTypeByName( "com.sun.star.container.XElementAccess" ),
)

# The component must have a ctor with the component context as argument.
def __init__( self, oContext ):
# Initialize the base class!
self.DannysUnoBaseClass_init( oContext )
# This is the list of items in the IndexContainer.
self.items = []

#----------------------------------------
# Interface: com.sun.star.container.XIndexContainer
#----------------------------------------

# void
# insertByIndex( [in] long nIndex,
# [in] any uElement );
def insertByIndex( self, nIndex, uElement ):
if nIndex < 0:
raise IndexOutOfBoundsException(
"""You specified an index that was less than zero.
""", self )
nItems = len( self.items )
if nIndex > nItems:
raise IndexOutOfBoundsException(
"""You specified an index that was greater than the last item in the container.
Since there are """ + str( nItems ) + """ items in the container, you must specify an
insert index that is from zero to """ + str( nItems ) + """.
""", self )
if nIndex == nItems:
self.items += [uElement]
return
self.items = self.items[:nIndex] + [uElement] + self.items[nIndex:]

# void
# removeByIndex( [in] long nIndex );
def removeByIndex( self, nIndex ):
if nIndex < 0:
raise IndexOutOfBoundsException(
"""You specified an index that was less than zero.
""", self )
nItems = len( self.items )
if nIndex > nItems:
raise IndexOutOfBoundsException(
"""You specified an index that was greater than or equal to the last item in the container.
Since there are """ + str( nItems ) + """ items in the container, you must specify an
insert index that is from zero to """ + str( nItems-1 ) + """.
""", self )
self.items = self.items[:nIndex] + self.items[nIndex+1:]

#----------------------------------------
# Interface: com.sun.star.container.XIndexReplace
#----------------------------------------

# void
# replaceByIndex( [in] long nIndes,
# [in] any uElement );
def replaceByIndex( self, nIndex, uElement ):
if nIndex < 0:
raise IndexOutOfBoundsException(
"""You specified an index that was less than zero.
""", self )
nItems = len( self.items )
if nIndex > nItems:
raise IndexOutOfBoundsException(
"""You specified an index that was greater than or equal to the last item in the container.
Since there are """ + str( nItems ) + """ items in the container, you must specify an
insert index that is from zero to """ + str( nItems-1 ) + """.
""", self )
self.items = self.items[:nIndex] + [uElement] + self.items[nIndex+1:]

#----------------------------------------
# Interface: com.sun.star.container.XIndexAccess
#----------------------------------------

# long
# getCount();
def getCount( self ):
return len( self.items )

# any
# getByIndex( [in] long nIndex );
def getByIndex( self, nIndex ):
if nIndex < 0:
raise IndexOutOfBoundsException(
"""You specified an index that was less than zero.
""", self )
nItems = len( self.items )
if nIndex > nItems:
raise IndexOutOfBoundsException(
"""You specified an index that was greater than or equal to the last item in the container.
Since there are """ + str( nItems ) + """ items in the container, you must specify an
insert index that is from zero to """ + str( nItems-1 ) + """.
""", self )
return self.items[ nIndex ]

#----------------------------------------
# Interface: com.sun.star.container.XElementAccess
#----------------------------------------

# type
# getElementType();
def getElementType( self ):
return None

# boolean
# hasElements();
def hasElements( self ):
return len( self.items ) > 0

# Add the class to the implementation container,
# which the loader uses to register/instantiate the component.
g_ImplementationHelper.addImplementation(
# The class
IndexContainer,
# The implementation name.
# Change this name for your own service.
IndexContainer.cServiceName,
# A list of services that that are implemented.
IndexContainer.tServiceNames,
)

##################################################################
from com.sun.star.lang import IndexOutOfBoundsException
from com.sun.star.container import ElementExistException
from com.sun.star.container import NoSuchElementException

class NameContainer( DannysUnoBaseClass ):
cServiceName = "name.dannyBrewer.util.NameContainer"
tServiceNames = ( cServiceName, )
tInterfaceTypes = DannysUnoBaseClass.tInterfaceTypes + (
uno.getTypeByName( "com.sun.star.container.XNameContainer" ),
uno.getTypeByName( "com.sun.star.container.XNameReplace" ),
uno.getTypeByName( "com.sun.star.container.XNameAccess" ),
uno.getTypeByName( "com.sun.star.container.XIndexAccess" ),
uno.getTypeByName( "com.sun.star.container.XElementAccess" ),
)

# The component must have a ctor with the component context as argument.
def __init__( self, oContext ):
# Initialize the base class!
self.DannysUnoBaseClass_init( oContext )
# This is the dictionary of items in the NameContainer.
self.items = {}

#----------------------------------------
# Interface: com.sun.star.container.XNameContainer
#----------------------------------------

# void
# insertByName( [in] string cName,
# [in] any uElement );
def insertByName( self, cName, uElement ):
if cName in self.items:
raise ElementExistException(
"""You specified an element name of \"""" + cName + """\"
which is already present in the container.
""", self )
self.items[ cName ] = uElement

# void
# removeByName( [in] string cName );
def removeByName( self, cName ):
if cName not in self.items:
raise NoSuchElementException(
"""You specified an element name of \"""" + cName + """\"
which does not exist in the container.
""", self )
del self.items[ cName ]

#----------------------------------------
# Interface: com.sun.star.container.XNameReplace
#----------------------------------------

# void
# replaceByName( [in] string cName,
# [in] any uElement );
def replaceByName( self, cName, uElement ):
if cName not in self.items:
raise NoSuchElementException(
"""You specified an element name of \"""" + cName + """\"
which does not exist in the container.
""", self )
self.items[ cName ] = uElement

#----------------------------------------
# Interface: com.sun.star.container.XNameAccess
#----------------------------------------

# any
# getByName( [in] string cName );
def getByName( self, cName ):
if cName not in self.items:
raise NoSuchElementException(
"""You specified an element name of \"""" + cName + """\"
which does not exist in the container.
""", self )
return self.items[ cName ]

# boolean
# hasByName( [in] string cName );
def hasByName( self, cName ):
return cName in self.items

# sequence< string >
# getElementNames();
def getElementNames( self ):
return tuple( self.items.keys() )

#----------------------------------------
# Interface: com.sun.star.container.XIndexAccess
#----------------------------------------

# long
# getCount();
def getCount( self ):
return len( self.items )

# any
# getByIndex( [in] long nIndex );
def getByIndex( self, nIndex ):
if nIndex < 0:
raise IndexOutOfBoundsException(
"""You specified an index that was less than zero.
""", self )
nItems = len( self.items )
if nIndex > nItems:
raise IndexOutOfBoundsException(
"""You specified an index that was greater than or equal to the last item in the container.
Since there are """ + str( nItems ) + """ items in the container, you must specify an
insert index that is from zero to """ + str( nItems-1 ) + """.
""", self )
return self.items.values()[ nIndex ]

#----------------------------------------
# Interface: com.sun.star.container.XElementAccess
#----------------------------------------

# type
# getElementType();
def getElementType( self ):
return None

# boolean
# hasElements();
def hasElements( self ):
return len( self.items ) > 0

# Add the class to the implementation container,
# which the loader uses to register/instantiate the component.
g_ImplementationHelper.addImplementation(
# The class
NameContainer,
# The implementation name.
# Change this name for your own service.
NameContainer.cServiceName,
# A list of services that that are implemented.
NameContainer.tServiceNames,
)</pre>

There are still some issues I am working out. I just want other interested people to be able to take my experimentation further or in different directions.

The above demonstrates several useful features.
* Component code written in pure python.
* Two services in one component.
* Two components which inherit from a base class which implements some of the underlying "plumbing" machinery.
* A way to inherit from multiple interfaces.

So why don't I just
from com.sun.star.container import XIndexAccess
and then just make my class do....
class IndexContainer( unohelper.Base, XIndexAccess )
[[Category:Python]][[Category:Uno]]

Documentation/DevGuide/Text/Inserting Tables

2010-04-30T05:55:17Z

Newacct:

{{Documentation/DevGuide/TextTOC
|Text2b=block
|TextTables=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Text/Text Table Properties
|NextPage=Documentation/DevGuide/Text/Accessing Existing Tables
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Text/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Inserting Tables}}
To create and insert a new text table, a five-step procedure must be followed:

# Get the service manager of the text document, querying the document's factory interface <idl>com.sun.star.lang.XMultiServiceFactory</idl>.
# Order a new text table from the factory by its service name "<code>com.sun.star.text.TextTable</code>", using the factory method <code>createInstance()</code>.
# From the object received, query the <idl>com.sun.star.text.XTextTable</idl> interface that inherits from <idl>com.sun.star.text.XTextContent</idl>.
# If necessary, initialize the table with the number of rows and columns. For this purpose, <code>XTextTable</code> offers the <code>initialize()</code> method.
# Insert the table into the text using the <code>insertTextContent()</code> method at its <idl>com.sun.star.text.XText</idl> interface. The method <code>insertTextContent()</code> expects an <code>XTextContent</code> to insert. Since <code>XTextTable</code> inherits from <code>XTextContent</code>, pass the <code>XTextTable</code> interface retrieved previously.

You are now ready to get cells, fill in text, values and formulas and set the table and cell properties as needed.

In the following code sample, there is a small helper function to put random numbers between -1000 and 1000 into the table to demonstrate formulas:


/** This method returns a random double which isn't too high or too low
*/
protected double getRandomDouble()
{
return (maRandom.nextInt(1000) * maRandom.nextDouble());
}

The following helper function inserts a string into a cell known by its name and sets its text color to white:


/** This method sets the text colour of the cell refered to by sCellName to white and inserts
the string sText in it
*/
public static void insertIntoCell(String sCellName, String sText, XTextTable xTable) {
// Access the XText interface of the cell referred to by sCellName
XText xCellText = (XText) UnoRuntime.queryInterface(
XText.class, xTable.getCellByName(sCellName));

// create a text cursor from the cells XText interface
XTextCursor xCellCursor = xCellText.createTextCursor();

// Get the property set of the cell's TextCursor
XPropertySet xCellCursorProps = (XPropertySet)UnoRuntime.queryInterface(
XPropertySet.class, xCellCursor);

try {
// Set the colour of the text to white
xCellCursorProps.setPropertyValue("CharColor", new Integer(16777215));
} catch (Exception e) {
e.printStackTrace(System.out);
}

// Set the text in the cell to sText
xCellText.setString(sText);
}

Using the above helper functions, create a text table and insert it into the text document.


/** This method shows how to create and insert a text table, as well as insert text and formulae
into the cells of the table
*/
protected void TextTableExample ()
{
try
{
// Create a new table from the document's factory
XTextTable xTable = (XTextTable) UnoRuntime.queryInterface(
XTextTable.class, mxDocFactory .createInstance(
"com.sun.star.text.TextTable" ) );

// Specify that we want the table to have 4 rows and 4 columns
xTable.initialize( 4, 4 );

// Insert the table into the document
mxDocText.insertTextContent( mxDocCursor, xTable, false);
// Get an XIndexAccess of the table rows
XIndexAccess xRows = xTable.getRows();

// Access the property set of the first row (properties listed in service description:
// com.sun.star.text.TextTableRow)
XPropertySet xRow = (XPropertySet) UnoRuntime.queryInterface(
XPropertySet.class, xRows.getByIndex ( 0 ) );
// If BackTransparant is false, then the background color is visible
xRow.setPropertyValue( "BackTransparent", Boolean.FALSE);
// Specify the color of the background to be dark blue
xRow.setPropertyValue( "BackColor", new Integer(6710932));

// Access the property set of the whole table
XPropertySet xTableProps = (XPropertySet)UnoRuntime.queryInterface(
XPropertySet.class, xTable );
// We want visible background colors
xTableProps.setPropertyValue( "BackTransparent", Boolean.FALSE);
// Set the background colour to light blue
xTableProps.setPropertyValue( "BackColor", new Integer(13421823));

// set the text (and text colour) of all the cells in the first row of the table
insertIntoCell( "A1", "First Column", xTable );
insertIntoCell( "B1", "Second Column", xTable );
insertIntoCell( "C1", "Third Column", xTable );
insertIntoCell( "D1", "Results", xTable );

// Insert random numbers into the first this three cells of each
// remaining row
xTable.getCellByName( "A2" ).setValue( getRandomDouble() );
xTable.getCellByName( "B2" ).setValue( getRandomDouble() );
xTable.getCellByName( "C2" ).setValue( getRandomDouble() );

xTable.getCellByName( "A3" ).setValue( getRandomDouble() );
xTable.getCellByName( "B3" ).setValue( getRandomDouble() );
xTable.getCellByName( "C3" ).setValue( getRandomDouble() );

xTable.getCellByName( "A4" ).setValue( getRandomDouble() );
xTable.getCellByName( "B4" ).setValue( getRandomDouble() );
xTable.getCellByName( "C4" ).setValue( getRandomDouble() );

// Set the last cell in each row to be a formula that calculates
// the sum of the first three cells
xTable.getCellByName( "D2" ).setFormula( "sum <A2:C2>" );
xTable.getCellByName( "D3" ).setFormula( "sum <A3:C3>" );
xTable.getCellByName( "D4" ).setFormula( "sum <A4:C4>" );
}
catch (Exception e)
{
e.printStackTrace ( System.out );
}
}

The next sample inserts auto text entries into a table, splitting cells during its course.


/** This example demonstrates the use of the AutoTextContainer, AutoTextGroup and AutoTextEntry services
and shows how to create, insert and modify auto text blocks
*/
protected void AutoTextExample ()
{
try
{
// Go to the end of the document
mxDocCursor.gotoEnd( false );
// Insert two paragraphs
mxDocText.insertControlCharacter ( mxDocCursor,
ControlCharacter.PARAGRAPH_BREAK, false );
mxDocText.insertControlCharacter ( mxDocCursor,
ControlCharacter.PARAGRAPH_BREAK, false );
// Position the cursor in the second paragraph
XParagraphCursor xParaCursor = (XParagraphCursor) UnoRuntime.queryInterface(
XParagraphCursor.class, mxDocCursor );
xParaCursor.gotoPreviousParagraph ( false );

// Get an XNameAccess interface to all auto text groups from the document factory
XNameAccess xContainer = (XNameAccess) UnoRuntime.queryInterface(
XNameAccess.class, mxFactory.createInstance (
"com.sun.star.text.AutoTextContainer" ) );

// Create a new table at the document factory
XTextTable xTable = (XTextTable) UnoRuntime.queryInterface(
XTextTable.class, mxDocFactory .createInstance(
"com.sun.star.text.TextTable" ) );

// Store the names of all auto text groups in an array of strings
String[] aGroupNames = xContainer.getElementNames();

// Make sure we have at least one group name
if ( aGroupNames.length > 0 )
{
// initialise the table to have a row for every autotext group
//in a single column + one
// additional row for a header
xTable.initialize( aGroupNames.length+1,1);

// Access the XPropertySet of the table
XPropertySet xTableProps = (XPropertySet)UnoRuntime.queryInterface(
XPropertySet.class, xTable );

// We want a visible background
xTableProps.setPropertyValue( "BackTransparent", Boolean.FALSE);

// We want the background to be light blue
xTableProps.setPropertyValue( "BackColor", new Integer(13421823));

// Insert the table into the document
mxDocText.insertTextContent( mxDocCursor, xTable, false);

// Get an XIndexAccess to all table rows
XIndexAccess xRows = xTable.getRows();

// Get the first row in the table
XPropertySet xRow = (XPropertySet) UnoRuntime.queryInterface(
XPropertySet.class, xRows.getByIndex ( 0 ) );

// We want the background of the first row to be visible too
xRow.setPropertyValue( "BackTransparent", Boolean.FALSE);

// And let's make it dark blue
xRow.setPropertyValue( "BackColor", new Integer(6710932));

// Put a description of the table contents into the first cell
insertIntoCell( "A1", "AutoText Groups", xTable);

// Create a table cursor pointing at the second cell in the first column
XTextTableCursor xTableCursor = xTable.createCursorByCellName ( "A2" );

// Loop over the group names
for ( int i = 0 ; i < aGroupNames.length ; i ++ )
{
// Get the name of the current cell
String sCellName = xTableCursor.getRangeName ();

// Get the XText interface of the current cell
XText xCellText = (XText) UnoRuntime.queryInterface (
XText.class, xTable.getCellByName ( sCellName ) );

// Set the cell contents of the current cell to be
//the name of the of an autotext group
xCellText.setString ( aGroupNames[i] );

// Access the autotext gruop with this name
XAutoTextGroup xGroup = ( XAutoTextGroup ) UnoRuntime.queryInterface (
XAutoTextGroup.class,xContainer.getByName(aGroupNames[i]));

// Get the titles of each autotext block in this group
String [] aBlockNames = xGroup.getTitles();

// Make sure that the autotext group contains at least one block
if ( aBlockNames.length > 0 )
{
// Split the current cell vertically into two seperate cells
xTableCursor.splitRange ( (short) 1, false );

// Put the cursor in the newly created right hand cell
// and select it
xTableCursor.goRight ( (short) 1, false );

// Split this cell horizontally to make a seperate cell
// for each Autotext block
if ( ( aBlockNames.length -1 ) > 0 )
xTableCursor.splitRange (
(short) (aBlockNames.length - 1), true );

// loop over the block names
for ( int j = 0 ; j < aBlockNames.length ; j ++ )
{
// Get the XText interface of the current cell
xCellText = (XText) UnoRuntime.queryInterface (
XText.class, xTable.getCellByName (
xTableCursor.getRangeName() ) );

// Set the text contents of the current cell to the
// title of an Autotext block
xCellText.setString ( aBlockNames[j] );

// Move the cursor down one cell
xTableCursor.goDown( (short)1, false);
}
}
// Go back to the cell we originally split
xTableCursor.gotoCellByName ( sCellName, false );

// Go down one cell
xTableCursor.goDown( (short)1, false);
}

XAutoTextGroup xGroup;
String [] aBlockNames;

// Add a depth so that we only generate 200 numbers before
// giving up on finding a random autotext group that contains autotext blocks
int nDepth = 0;
do
{
// Generate a random, positive number which is lower than
// the number of autotext groups
int nRandom = maRandom.nextInt( aGroupNames.length );

// Get the autotext group at this name
xGroup = ( XAutoTextGroup ) UnoRuntime.queryInterface (
XAutoTextGroup.class, xContainer.getByName (
aGroupNames[ nRandom ] ) );

// Fill our string array with the names of all the blocks in this
// group
aBlockNames = xGroup.getElementNames();

// increment our depth counter
++nDepth;
}
while ( nDepth < 200 && aBlockNames.length == 0 );
// If we managed to find a group containg blocks...
if ( aBlockNames.length > 0 )
{
// Pick a random block in this group and get it's
// XAutoTextEntry interface
int nRandom = maRandom.nextInt( aBlockNames.length );
XAutoTextEntry xEntry = ( XAutoTextEntry )
UnoRuntime.queryInterface (
XAutoTextEntry.class, xGroup.getByName (
aBlockNames[ nRandom ] ) );
// insert the modified autotext block at the end of the document
xEntry.applyTo ( mxDocCursor );

// Get the titles of all text blocks in this AutoText group
String [] aBlockTitles = xGroup.getTitles();

// Get the XNamed interface of the autotext group
XNamed xGroupNamed = ( XNamed ) UnoRuntime.queryInterface (
XNamed.class, xGroup );

// Output the short cut and title of the random block
//and the name of the group it's from
System.out.println ( "Inserted the Autotext '" + aBlockTitles[nRandom]
+ "', shortcut '" + aBlockNames[nRandom] + "' from group '"
+ xGroupNamed.getName() );
}
}

// Go to the end of the document
mxDocCursor.gotoEnd( false );
// Insert new paragraph
mxDocText.insertControlCharacter (
mxDocCursor, ControlCharacter.PARAGRAPH_BREAK, false );

// Position cursor in new paragraph
xParaCursor.gotoPreviousParagraph ( false );

// Insert a string in the new paragraph
mxDocText.insertString ( mxDocCursor, "Some text for a new autotext block", false );

// Go to the end of the document
mxDocCursor.gotoEnd( false );
}
catch (Exception e)
{
e.printStackTrace ( System.out );
}
}

{{PDL1}}

[[Category:Documentation/Developer's Guide/Text Documents]]

ES/Desarrollo/Syndication

2010-04-28T19:27:16Z

Newacct:

{{DISPLAYTITLE:Syndicating the OOo Website}}

This script will parse and syndicate [[OOoES|OOoES]] Announcement section and then register it to a Database Backend. This is still a simple script and has no other functionality than parse the annoucment page you can change the project subdomain and you will be able to parse your announcments.

TODO:
<ul>
<li>Loop over multiple urls</li>
<li>Parse other documents such as Documentation</li>
</ul>

<source lang="python">
#!/usr/bin/env python
# -*- coding: utf-8 -*-

###########################################################################
# Copyright (C) 2005 by Alexandro Colorado && Luis Cabrera
#
# Author:
# Alexandro Colorado <jza@openoffice.org>
# Luis Cabrera <lcabrera@sauco.org>
#
# Copyright: See COPYING file that comes with this distribution
#
###########################################################################

__shell_usage__ = '''Este programa esta pensado para recoger automaticamente
los enlaces localizados en una determinada pagina, compararlos con los ya
existentes en una bbdd, y, si hay nuevos enlaces, insertarlos en la bbdd y
posteriormente, mandar un correo a las listas de usuarios predeterminadas
con los enlaces a las nuevas noticias.
Si no hubieran noticias nuevas, el programa no debera hacer absolutamente
nada.
'''
__version__ = '20051024'
__author__='Luis Cabrera Sauco && Alexandro Colorado'

import HTMLParser
import urllib2
import MySQLdb
import smtplib

############ CONFIGURATION VARIABLES ###############

'''Pagina de la que recoger los enlaces iniciales'''
headlines_url = ''

'''Datos para la configuracia de la bbdd'''
myhost= ""
myuser=""
mypassword=""
mydb=""
mytb=""

'''Datos para el envio de correos de avisos'''
enviar_correo=1
remitente=""
destinatario=""
subject=""
##
###################################

class HeadlinesParser(HTMLParser.HTMLParser):
def __init__(self):
HTMLParser.HTMLParser.__init__(self)
self.headlines = {}
self.while_anchor = False
self.last_href = None

def handle_starttag(self, name, attrs):
attrs = dict(attrs)
if name == "a":
if "href" in attrs:
current_href = attrs["href"]
if "newsItemID" in current_href:
self.while_anchor = True
self.last_href = current_href

def handle_data(self, content):
content = content.strip()
if self.while_anchor:
self.headlines[content] = self.last_href

def handle_endtag(self, name):
if name == "a":
self.while_anchor = False

def sendMessage(de, para=[], cc=[], asunto='Asunto',texto='Cuerpo.', archivos=[],
host='', charsettexto='iso-8859-1', loginUsername='', loginPassword=''):
""" Mandar mensaje por correo electronico. """

from email.MIMEBase import MIMEBase
from email.MIMEText import MIMEText
from email import Encoders
import mimetypes
from smtplib import SMTP
import os

msg=MIMEText(texto, _charset=charsettexto)
if archivos:
msg2=MIMEBase("multipart","mixed") # crear contenedor
msg2.preamble="Este es un mensaje MIME con varias partes."

# es muy importante!!! (de lo contrario no reconoce primer anexo.)
msg2.epilogue=''
msg2.add_payload(msg)
msg=msg2

# Cabeceras primero
msg['From']=de
if isinstance(para,basestring): para=[para]
msg['To']=", ".join(para)
if cc:
if isinstance(cc,basestring): cc=[cc]
msg['Cc']=", ".join(cc)
para.extend(cc)
msg['Subject']=asunto

for archivo in archivos:
ctype, encoding = mimetypes.guess_type(archivo)
if ctype is None or encoding is not None:
ctype = 'application/octet-stream'
maintype, subtype = ctype.split('/', 1)
if maintype == 'text':
msgparte = MIMEText(file(archivo).read(), _subtype=subtype)
else:
msgparte = MIMEBase(maintype, subtype)
msgparte.add_payload(file(archivo,"rb").read())
# Encode the payload using Base64
Encoders.encode_base64(msgparte)
msgparte.add_header('Content-Disposition', 'attachment',
filename=os.path.basename(archivo))
msg.attach(msgparte)

if not host:
return msg.as_string(0)
s=SMTP(host)
if loginUsername and loginPassword:
s.login(loginUserName,loginPassword)
x=s.sendmail(de,para, msg.as_string(0))
s.quit()
return x

def conectarBD():
"""Rutina de conexion a la BBDD"""

try:
db = MySQLdb.Connect(host=myhost,user=myuser,passwd=mypassword,db=mydb)
return db
except:
print u"Error en la conexion a la Base de Datos"
return -1

def insertarHeadLines(datos):
"""Funcion para insertar los enlaces en mysql"""

conn = conectarBD()
c = conn.cursor()

if (conn != -1):
try:
"""Insertamos los links"""
for headline in datos:
try:
titulo_noticia = headline[0].decode('utf8').encode('latin1')
enlace_noticia = headline[1]
c.execute('''INSERT INTO mytb (headline, url) VALUES ('s')''' % ( titulo_noticia, enlace_noticia ))
referencia_noticia = 'Acaba de ser a adida la siguiente noticia:
'+titulo_noticia+'

Pueden leer la noticia completa en el siguiente enlace:
'+enlace_noticia
referencia_noticia = referencia_noticia.decode('utf8').encode('latin1')
if enviar_correo == 1:
sendMessage(de=remitente,para=destinatario,asunto=subject,
texto=referencia_noticia,host="localhost")
except:
pass
## print u'Enlace repetido'
except:
print u'Problemas al realizar los INSERT'
return -1
def main():
"""LLamada a las distintas funciones para conseguir los objetivos del programa"""

source = urllib2.urlopen(headlines_url).read()
parser = [[Main_HeadlinesParser|HeadlinesParser]]()
parser.feed(source)

lineas = parser.headlines.items()

try:
insertar[[Main_HeadLines|HeadLines]](lineas)
except:
print u'Problemas al insertar los enlaces.'

if __name__ == "__main__":
main()
</source>
<hr />
Second script: Parse Documentation Page
<source lang="python">
#!/usr/bin/env python
# -*- coding: latin1 -*-

###########################################################################
# Copyright (C) 2005 by Alexandro Colorado && Luis Cabrera
#
# Author:
# Alexandro Colorado <jza@openoffice.org>
# Luis Cabrera <lcabrera@sauco.org>
#
# Copyright: See COPYING file that comes with this distribution
#
###########################################################################

__shell_usage__ = '''
'''
__version__ = '20051030'
__author__='Luis Cabrera Sauco'

import HTMLParser
import urllib2

headlines_url = 'http://es.openoffice.org/servlets/ProjectDocumentList?folderID=276&expandFolder=276&folderID=0'

class HeadlinesParser(HTMLParser.HTMLParser):
def __init__(self):
HTMLParser.HTMLParser.__init__(self)
self.headlines = {}
self.while_anchor = False
self.last_href = None
self.mysearch = 'ProjectDocumentList'

def handle_starttag(self, name, attrs):
attrs = dict(attrs)
if name == "a":
if "href" in attrs:
current_href = attrs["href"]
if self.mysearch in current_href:
self.while_anchor = True
self.last_href = current_href

def handle_data(self, content):
content = content.strip()
if self.while_anchor:
self.headlines[content] = self.last_href

def handle_endtag(self, name):
if name == "a":
self.while_anchor = False

def main():
source = urllib2.urlopen(headlines_url).read()
parser = HeadlinesParser()
parser.feed(source)

for headline in parser.headlines.items():
# print '''insert into "Headlines" values ('s');''' % headline
urldoc = headline[1].decode('utf8').encode('latin1')
docsource = urllib2.urlopen(urldoc).read()
docparser = HeadlinesParser()
docparser.mysearch = 'documents'
docparser.feed(docsource)

for datos in docparser.headlines.items():
print '''insert into "Headlines" values ('s',' (headline[0],datos[0].decode('utf8').encode('latin1'),datos[1].decode('utf8').encode('latin1'))

if __name__ == "__main__":
main()

</source>

-- AlexandroColorado - 23 Oct 2005 
-- LuisCabreraSauco - 02 Nov 2005
[[Category:NLC]] [[Category:OOoES]]

Documentation/DevGuide/WritingUNO/Disable Commands

2010-04-17T00:32:39Z

Newacct:

{{Documentation/DevGuide/WritingUNOTOC
|WritingUNO2e=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/WritingUNO/AddOns/Installation
|NextPage=Documentation/DevGuide/WritingUNO/Intercepting Context Menus
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/WritingUNO/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Disable Commands}}
In {{PRODUCTNAME}}, there may be situations where functions should be disabled to prevent users from changing or destroying documents inadvertently. {{PRODUCTNAME}} maintains a list of disabled commands that can be maintained by users and developers through the configuration API.

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

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

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

[[Image:DisableCommands_ApplicationFlow.png|none|thumb|400px|How the disable commands feature works]]

{{Documentation/Caution|Since the disable commands implementation is the first part in the dispatch chain, there is no way to circumvent it. The disabled command must be removed from the list, otherwise it remains disabled.}}

=== Configuration ===

The disable commands feature uses the configuration branch ''org.openoffice.Office.Commands'' to read which commands should be disabled. The following schema applies:
<source lang="xml">
<?xml version='1.0' encoding='UTF-8'?>
<oor:component-schema oor:name="Commands" oor:package="org.openoffice.Office" xml:lang="en-US" xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<templates>
<group oor:name="CommandType">
<prop oor:name="Command" oor:type="xs:string"/>
</group>
</templates>
<component>
<group oor:name="Execute">
<set oor:name="Disabled" oor:node-type="CommandType"/>
</group>
</component>
</oor:component-schema>
</source>
The configuration schema for disabled commands is very simple. The ''org.openoffice.Office.Commands'' branch has a group called <code>Execute</code>. This group has only one set called <code>Disabled</code>. The <code>Disabled</code> set supports nodes of the type <code>CommandType</code>. The following table describes the supported properties of <code>CommandType</code>.

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
!colspan="2"|Properties of the <code>CommandType</code> group
|-
|<code>oor:component-data</code>
|string. It must be unique inside the <code>Disabled</code> set, but has no additional meaning for the implementation of the disable commands feature. Use a consecutive numbering scheme; even numbers are allowed.
|-
|<code>Command</code>
|string. This is the command name with the preceding protocol. That means the command URL ''.uno:Open'' (which shows the '''File – Open''' dialog) must be written as <code>Open</code>.
The valid commands can be found in the document ''Index of Command Names'' in the [http://framework.openoffice.org/servlets/ProjectDocumentList Documentation section of the framework project] on the OpenOffice.org web page. The {{PRODUCTNAME}} SDK also includes the latest [http://www.openoffice.org/files/documents/25/60/commands_11beta.html list of command names].
Additional information regarding Command names is available in: [http://wiki.services.openoffice.org/wiki/Framework/Article/OpenOffice.org_2.x_Commands]
|}

The example below shows a configuration file that disables the commands for '''File – Open''', '''Edit – Select All''', '''Help – About {{PRODUCTNAME}}''' and '''File – Exit'''.
<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<oor:component-data oor:name="Commands" oor:package="org.openoffice.Office" xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<node oor:name="Execute">
<node oor:name="Disabled">
<node oor:name="com.mycompany.a-chosen-unique-name.m1" oor:op="replace">
<prop oor:name="Command">
<value>Open</value>
</prop>
</node>
<node oor:name="com.mycompany.a-chosen-unique-name.m2" oor:op="replace">
<prop oor:name="Command">
<value>SelectAll</value>
</prop>
</node>
<node oor:name="com.mycompany.a-chosen-unique-name.m3" oor:op="replace">
<prop oor:name="Command">
<value>About</value>
</prop>
</node>
<node oor:name="com.mycompany.a-chosen-unique-name.m4" oor:op="replace">
<prop oor:name="Command">
<value>Quit</value>
</prop>
</node>
</node>
</node>
</oor:component-data>
</source>

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

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

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

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

=== Disabling Commands at Runtime ===


The following code example first removes all commands that were defined in the user layer of the configuration branch <code>org.openoffice.Office.Commands</code> as having a defined starting point. Then it checks if it can get dispatch objects for some pre-defined commands.Then the example disables these commands and tries to get dispatch objects for them again. At the end, the code removes the disabled commands again, otherwise {{PRODUCTNAME}} would not be fully usable any longer.
<source lang="java">
import com.sun.star.bridge.XUnoUrlResolver;
import com.sun.star.uno.UnoRuntime;
import com.sun.star.uno.XComponentContext;
import com.sun.star.lang.XMultiComponentFactory;
import com.sun.star.beans.XPropertySet;
import com.sun.star.beans.PropertyValue;
import com.sun.star.lang.XMultiServiceFactory;
import com.sun.star.lang.XSingleServiceFactory;
import com.sun.star.util.XURLTransformer;
import com.sun.star.frame.XDesktop;

import com.sun.star.beans.UnknownPropertyException;

/*
* Provides example code how to enable/disable
* commands.
*/
public class DisableCommandsTest extends java.lang.Object {

/*
* A list of command names
*/
final static private String[] aCommandURLTestSet =
{
"Open",
"About",
"SelectAll",
"Quit",
};

private static XComponentContext xRemoteContext = null;
private static XMultiComponentFactory xRemoteServiceManager = null;
private static XURLTransformer xTransformer = null;
private static XMultiServiceFactory xConfigProvider = null;

/*
* @param args the command line arguments
*/
public static void main(String[] args) {

try {
// connect
XComponentContext xLocalContext =
com.sun.star.comp.helper.Bootstrap.createInitialComponentContext(null);
XMultiComponentFactory xLocalServiceManager = xLocalContext.getServiceManager();
Object urlResolver = xLocalServiceManager.createInstanceWithContext(
"com.sun.star.bridge.UnoUrlResolver", xLocalContext);
XUnoUrlResolver xUnoUrlResolver = (XUnoUrlResolver) UnoRuntime.queryInterface(
XUnoUrlResolver.class, urlResolver );
Object initialObject = xUnoUrlResolver.resolve(
"uno:socket,host=localhost,port=2083;urp;StarOffice.ServiceManager");
XPropertySet xPropertySet = (XPropertySet)UnoRuntime.queryInterface(
XPropertySet.class, initialObject);
Object context = xPropertySet.getPropertyValue("DefaultContext");
xRemoteContext = (XComponentContext)UnoRuntime.queryInterface(
XComponentContext.class, context);
xRemoteServiceManager = xRemoteContext.getServiceManager();
Object transformer = xRemoteServiceManager.createInstanceWithContext(
"com.sun.star.util.URLTransformer", xRemoteContext);
xTransformer = (com.sun.star.util.XURLTransformer)UnoRuntime.queryInterface(
com.sun.star.util.XURLTransformer.class, transformer);

Object configProvider = xRemoteServiceManager.createInstanceWithContext(
"com.sun.star.configuration.ConfigurationProvider", xRemoteContext);
xConfigProvider = (com.sun.star.lang.XMultiServiceFactory)UnoRuntime.queryInterface(
com.sun.star.lang.XMultiServiceFactory.class, configProvider);

// First we need a defined starting point. So we have to remove
// all commands from the disabled set!
enableCommands();

// Check if the commands are usable
testCommands(false);

// Disable the commands
disableCommands();

// Now the commands should not be usable anymore
testCommands(true);

// Remove disable commands to make Office usable again
enableCommands();
}
catch (java.lang.Exception e){
e.printStackTrace();
}
finally {
System.exit(0);
}
}

/**
* Test the commands that we enabled/disabled
*/
private static void testCommands(boolean bDisabledCmds) throws com.sun.star.uno.Exception {
// We need the desktop to get access to the current frame
Object desktop = xRemoteServiceManager.createInstanceWithContext(
"com.sun.star.frame.Desktop", xRemoteContext );
com.sun.star.frame.XDesktop xDesktop = (com.sun.star.frame.XDesktop)UnoRuntime.queryInterface(
com.sun.star.frame.XDesktop.class, desktop);
com.sun.star.frame.XFrame xFrame = xDesktop.getCurrentFrame();
com.sun.star.frame.XDispatchProvider xDispatchProvider = null;
if (xFrame != null) {
// We have a frame. Now we need access to the dispatch provider.
xDispatchProvider = (com.sun.star.frame.XDispatchProvider)UnoRuntime.queryInterface(
com.sun.star.frame.XDispatchProvider.class, xFrame );
if (xDispatchProvider != null) {
// As we have the dispatch provider we can now check if we get a dispatch
// object or not.
for (int n = 0; n < aCommandURLTestSet.length; n++) {
// Prepare the URL
com.sun.star.util.URL[] aURL = new com.sun.star.util.URL[1];
aURL[0] = new com.sun.star.util.URL();
com.sun.star.frame.XDispatch xDispatch = null;

aURL[0].Complete = ".uno:" + aCommandURLTestSet[n];
xTransformer.parseSmart(aURL, ".uno:");

// Try to get a dispatch object for our URL
xDispatch = xDispatchProvider.queryDispatch(aURL[0], "", 0);

if (xDispatch != null) {
if (bDisabledCmds)
System.out.println("Something is wrong, I got dispatch object for "
+ aURL[0].Complete);
else
System.out.println("Ok, dispatch object for " + aURL[0].Complete);
}
else {
if (!bDisabledCmds)
System.out.println("Something is wrong, I cannot get dispatch object for "
+ aURL[0].Complete);
else
System.out.println("Ok, no dispatch object for " + aURL[0].Complete);
}
resetURL(aURL[0]);
}
}
else
System.out.println("Couldn't get XDispatchProvider from Frame!");
}
else
System.out.println("Couldn't get current Frame from Desktop!");
}

/**
* Ensure that there are no disabled commands in the user layer. The
* implementation removes all commands from the disabled set!
*/
private static void enableCommands() {
// Set the root path for our configuration access
com.sun.star.beans.PropertyValue[] lParams = new com.sun.star.beans.PropertyValue[1];

lParams[0] = new com.sun.star.beans.PropertyValue();
lParams[0].Name = "nodepath";
lParams[0].Value = "/org.openoffice.Office.Commands/Execute/Disabled";

try {
// Create configuration update access to have write access to the configuration
Object xAccess = xConfigProvider.createInstanceWithArguments(
"com.sun.star.configuration.ConfigurationUpdateAccess", lParams);

com.sun.star.container.XNameAccess xNameAccess = (com.sun.star.container.XNameAccess)
UnoRuntime.queryInterface(com.sun.star.container.XNameAccess.class, xAccess);
if (xNameAccess != null) {
// We need the XNameContainer interface to remove the nodes by name
com.sun.star.container.XNameContainer xNameContainer =
(com.sun.star.container.XNameContainer)
UnoRuntime.queryInterface(com.sun.star.container.XNameContainer.class, xAccess);

// Retrieves the names of all Disabled nodes
String[] aCommandsSeq = xNameAccess.getElementNames();
for (int n = 0; n < aCommandsSeq.length; n++) {
try {
// remove the node
xNameContainer.removeByName( aCommandsSeq[n]);
}
catch (com.sun.star.lang.WrappedTargetException e) {
}
catch (com.sun.star.container.NoSuchElementException e) {
}
}
}

// Commit our changes
com.sun.star.util.XChangesBatch xFlush =
(com.sun.star.util.XChangesBatch)UnoRuntime.queryInterface(
com.sun.star.util.XChangesBatch.class, xAccess);
xFlush.commitChanges();
}
catch (com.sun.star.uno.Exception e) {
System.out.println("Exception detected!");
System.out.println(e);
}
}

/**
* Disable all commands defined in the aCommandURLTestSet array
*/
private static void disableCommands() {
// Set the root path for our configuration access
com.sun.star.beans.PropertyValue[] lParams = new com.sun.star.beans.PropertyValue[1];
lParams[0] = new com.sun.star.beans.PropertyValue();
lParams[0].Name = "nodepath";
lParams[0].Value = "/org.openoffice.Office.Commands/Execute/Disabled";

try {
// Create configuration update access to have write access to the configuration
Object xAccess = xConfigProvider.createInstanceWithArguments(
"com.sun.star.configuration.ConfigurationUpdateAccess", lParams);

com.sun.star.lang.XSingleServiceFactory xSetElementFactory =
(com.sun.star.lang.XSingleServiceFactory)UnoRuntime.queryInterface(
com.sun.star.lang.XSingleServiceFactory.class, xAccess);

com.sun.star.container.XNameContainer xNameContainer =
(com.sun.star.container.XNameContainer)UnoRuntime.queryInterface(
com.sun.star.container.XNameContainer.class, xAccess );

if (xSetElementFactory != null && xNameContainer != null) {
Object[] aArgs = { };

for (int i = 0; i < aCommandURLTestSet.length; i++) {
// Create the nodes with the XSingleServiceFactory of the configuration
Object xNewElement = xSetElementFactory.createInstanceWithArguments( aArgs );
if (xNewElement != null) {
// We have a new node. To set the properties of the node we need
// the XPropertySet interface.
com.sun.star.beans.XPropertySet xPropertySet =
(com.sun.star.beans.XPropertySet)UnoRuntime.queryInterface( com.sun.star.beans.XPropertySet.class,
xNewElement );

if (xPropertySet != null) {
// Create a unique node name.
String aCmdNodeName = "Command-";
aCmdNodeName += i;

// Insert the node into the Disabled set
xPropertySet.setPropertyValue("Command", aCommandURLTestSet[i]);
xNameContainer.insertByName(aCmdNodeName, xNewElement);
}
}
}

// Commit our changes
com.sun.star.util.XChangesBatch xFlush = (com.sun.star.util.XChangesBatch)
UnoRuntime.queryInterface(com.sun.star.util.XChangesBatch.class, xAccess);
xFlush.commitChanges();
}
}
catch (com.sun.star.uno.Exception e) {
System.out.println("Exception detected!");
System.out.println(e);
}
}

/**
* reset URL so it can be reused
*
* @param aURL
* the URL that should be reseted
*/
private static void resetURL(com.sun.star.util.URL aURL) {
aURL.Protocol = "";
aURL.User = "";
aURL.Password = "";
aURL.Server = "";
aURL.Port = 0;
aURL.Path = "";
aURL.Name = "";
aURL.Arguments = "";
aURL.Mark = "";
aURL.Main = "";
aURL.Complete = "";
}
}
</source>
{{PDL1}}

[[Category:Documentation/Developer's Guide/Writing UNO Components]]

Documentation/DevGuide/Spreadsheets/Function Handling

2010-04-17T00:31:54Z

Newacct:

{{Documentation/DevGuide/SpreadsheetsTOC
|SpreadsheetDocs2d=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Spreadsheets/Overall Document Features
|NextPage=Documentation/DevGuide/Spreadsheets/Settings
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Spreadsheets/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Function Handling}}
This section describes the services which handle spreadsheet functions.

=== Calculating Function Results ===


The <idl>com.sun.star.sheet.FunctionAccess</idl> service calls any spreadsheet function and gets its result without having to insert a formula into a spreadsheet document.

[[Image:FunctionHandlingUML1.png|none|thumb|400px|FunctionAccess]]

The service can be instantiated through the service manager. The <idl>com.sun.star.sheet.XFunctionAccess</idl> interface contains only one method, <code>callFunction()</code>. The first parameter is the name of the function to call. The name has to be the function's programmatic name.

* For a built-in function, the English name is always used, regardless of the application's UI language.
* For an add-in function, the complete internal name that is the add-in component's service name, followed by a dot and the function's name as defined in the interface. For the <code>getIncremented</code> function in the example from the add-in section, this would be: "<code>com.sun.star.sheet.addin.ExampleAddIn.getIncremented</code>".

The second parameter to <code>callFunction()</code> is a sequence containing the function arguments. The supported types for each argument are described in the <idl>com.sun.star.sheet.XFunctionAccess</idl> interface description, and are similar to the argument types for add-in functions. The following example passes two arguments to the <code>ZTEST</code> function, an array of values and a single value.


<source lang="java">// --- Calculate a function ---
Object aFuncInst = xServiceManager.createInstance("com.sun.star.sheet.FunctionAccess");
com.sun.star.sheet.XFunctionAccess xFuncAcc = (com.sun.star.sheet.XFunctionAccess)
UnoRuntime.queryInterface(com.sun.star.sheet.XFunctionAccess.class, aFuncInst);
// put the data into a two-dimensional array
double[][] aData = {{1.0, 2.0, 3.0}};
// construct the array of function arguments
Object[] aArgs = { aData, new Double( 2.0 ) };
Object aResult = xFuncAcc.callFunction("ZTEST", aArgs);
System.out.println("ZTEST result for data {1,2,3} and value 2 is "
+ ((Double)aResult).doubleValue()); </source>

In Calc, an argument of the function may accept a range of cells, e.g <code>=SUM(B12:G55)</code>. When calling a spreadsheet function, a range argument is transmitted as an array with two dimensions. The first corresponds to the row, the second corresponds to the column, indexes are zero-based.

{{Documentation/Note|The implementation of <idl>com.sun.star.sheet.FunctionAccess</idl> uses the same internal structures as a spreadsheet document, therefore it is bound by the same limitations, such as the limit of 65536 rows and 1024 columns for the function arguments.}}

=== Information about Functions ===


The services <idl>com.sun.star.sheet.FunctionDescriptions</idl> and <idl>com.sun.star.sheet.FunctionDescription</idl> provide help texts about the available spreadsheet cell functions, including add-in functions and their arguments. This is the same information that {{PRODUCTNAME}} API Calc displays in the function AutoPilot.

[[Image:FunctionHandlingUML2.png|none|thumb|400px|FunctionDescriptions]]

The <idl>com.sun.star.sheet.FunctionDescriptions</idl> service is instantiated through the service manager. It provides three different methods to access the information for the different functions:

* By name through the <idl>com.sun.star.container.XNameAccess</idl> interface.
* By index through the <idl>com.sun.star.container.XIndexAccess</idl> interface.
* By function identifier through the <idl>com.sun.star.sheet.XFunctionDescriptions</idl> interface's <code>getById()</code> method. The function identifier is the same used in the <idl>com.sun.star.sheet.RecentFunctions</idl> service.

The <idl>com.sun.star.sheet.FunctionDescription</idl> that is returned by any of these calls is a sequence of <idl>com.sun.star.beans.PropertyValue</idl> structs. To access one of these properties, loop through the sequence, looking for the desired property's name in the Name member. The Arguments property contains a sequence of <idl>com.sun.star.sheet.FunctionArgument</idl> structs, one for each argument that the function accepts. The struct contains the name and description of the argument, as well as a boolean flag showing if the argument is optional.

{{Documentation/Note|All of the strings contained in the <idl>com.sun.star.sheet.FunctionDescription</idl> service are to be used in user interaction, and therefore translated to the application's UI language. They cannot be used where programmatic function names are expected, for example, the <idl>com.sun.star.sheet.FunctionAccess</idl> service.}}

The Recently Used Functions section below provides an example on how to use the <idl>com.sun.star.sheet.FunctionDescriptions</idl> service.

=== Recently Used Functions ===


The <idl>com.sun.star.sheet.RecentFunctions</idl> service provides access to the list of recently used functions of the spreadsheet application, that is displayed in the '''AutoPilot:Functions''' and the '''Function List''' window for example.

[[Image:FunctionHandlingUML3.png|none|thumb|400px|RecentFunctions]]

The service can be instantiated through the service manager. The <idl>com.sun.star.sheet.XRecentFunctions</idl> interface's <code>getRecentFunctionIds()</code> method returns a sequence of function identifiers that are used with the <idl>com.sun.star.sheet.FunctionDescriptions</idl> service. The <code>setRecentFunctionIds()</code> method changes the list. If the parameter to the <code>setRecentFunctionIds()</code> call contains more entries than the application handles, only the first entries are used. The maximum size of the list of recently used functions, currently 10, can be queried with the <code>getMaxRecentFunctions()</code> method.

The following example demonstrates the use of the <idl>com.sun.star.sheet.RecentFunctions</idl> and <idl>com.sun.star.sheet.FunctionDescriptions</idl> services.

<source lang="java">
// --- Get the list of recently used functions ---
Object aRecInst = xServiceManager.createInstance("com.sun.star.sheet.RecentFunctions");
com.sun.star.sheet.XRecentFunctions xRecFunc = (com.sun.star.sheet.XRecentFunctions)
UnoRuntime.queryInterface(com.sun.star.sheet.XRecentFunctions.class, aRecInst);
int[] nRecentIds = xRecFunc.getRecentFunctionIds();

// --- Get the names for these functions ---
Object aDescInst = xServiceManager.createInstance("com.sun.star.sheet.FunctionDescriptions");
com.sun.star.sheet.XFunctionDescriptions xFuncDesc = (com.sun.star.sheet.XFunctionDescriptions)
UnoRuntime.queryInterface(com.sun.star.sheet.XFunctionDescriptions.class, aDescInst);
System.out.print("Recently used functions: ");
for (int nFunction=0; nFunction<nRecentIds.length; nFunction++) {
com.sun.star.beans.PropertyValue[] aProperties = xFuncDesc.getById(nRecentIds[nFunction]);
for (int nProp=0; nProp<aProperties.length; nProp++)
if (aProperties[nProp].Name.equals("Name"))
System.out.print(aProperties[nProp].Value + " ");
}
System.out.println();
</source>

{{PDL1}}

[[Category:Documentation/Developer's Guide/Spreadsheet Documents]]

General UNO Component Project Type

2010-03-28T04:25:10Z

Newacct:

Back to [[OpenOffice_NetBeans_Integration|OpenOffice.org NetBeans Integration]]

__TOC__

= Overview =

The OpenOffice.org Component wizard creates a new project based on a J2SE class library project and supports additional targets to create a complete OpenOffice.org extension package and to deploy this package into the configured OpenOffice.org installation. 
The wizard collects all necessary information and allows you to select the existing services and interfaces that should be implemented. In the same wizard step you can also define completely new services and interfaces (and additional data types based on IDL) to design abstract interfaces for completely new functionality. 
After finishing the wizard you can directly build the project and can create and deploy the OpenOffice.org extension package. All interface methods are implemented by default, and do nothing. In a second step you can insert your implementation in the generated skeleton, rebuild the extension and deploy it again to see the effect.

= Project Wizard =
The project wizard is quite simple to use, you simply choose
*'' '''File -> New Project -> OpenOffice.org -> OpenOffice.org Component''' ''
and follow the wizard.

* '''Step 1''': Select the project type
 [[Image:Component1.png|center]] 
* '''Step 2''': Define the project name, implementation class name, an package and the project location
 [[Image:Component2.png|center]] 
* '''Step 4''': Specifiy or define the UNO IDL services and interfaces which should be implemented.
** To provide an own defined interface, choose the '''Interface''' node and click on '''Define New Data Type''' [[Image:Component_Interface1.png|center]] 
** Create the interface as shown in this picture [[Image:Component_Interface.png|center]] 
** Back at the New Project window, select the '''Service''' node and click again on '''Define New Data Type'''. Create the service as follows: [[Image:Component_Service.png|center]] 
** Back at the New Project window, click on '''Add Service/Interface'''. Select the new created service. The interface will be added automatically: [[Image:Component_TypeBrowser.png|center]] 
** When everything looks like this, click '''OK''': [[Image:Component3.png|center]] 

You can simply create or deploy the '''oxt''' extension package by choosing: 
::'''Project View -> Project Node -> Context Menu -> Deploy and Run Extension in OpenOffice.org''' 

When you have deployed the package, the usage of the new UNO component in OpenOffice.org is straight forward. Either you have implemented a special service provider interface (SPI) and can use it in the same way as any other implementations of this SPI can be used, or you have defined some new service and/or interfaces and can instantiate your component as a normal service over the global service manager.

= Generated Code =
The wizard generates more code for a UNO component, but it depends on the selected UNO IDL types. If only existing types are selected and no new UNO IDL types are defined, the wizard will not generate any UNO IDL files. For the example shown above, the following files are generated:

* '''uno-extension-manifest.xml''' the package descriptor, will be packed as "META-INF/manifest.xml". The content of the uno-extension-manifest.xml depends on the selection or definition of the IDL types. If no new types are defined, no type library is specified. Own IDL types are packed in an additional jar referenced here. Without new IDL types, this jar will also not exist.
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<manifest:manifest xmlns:manifest="http://openoffice.org/2001/manifest">
<manifest:file-entry manifest:media-type="application/vnd.sun.star.uno-typelibrary;type=RDB"
manifest:full-path="types.rdb"/>
<manifest:file-entry manifest:media-type="application/vnd.sun.star.uno-component;type=Java"
manifest:full-path="TestComponent.jar"/>
<manifest:file-entry manifest:media-type="application/vnd.sun.star.uno-typelibrary;type=Java"
manifest:full-path="TestComponent_IDL_types.jar"/>
</manifest:manifest>
</source>
* '''org/openoffice/test/MyTestService.idl''' the test service definition
<source lang="idl">
/*
* MyTestService.idl
*
* Created on 11.09.2006 - 17:42:17
*
*/

#ifndef _org_openoffice_test_MyTestService_
#define _org_openoffice_test_MyTestService_

#include "XMyTest.idl"

module org { module openoffice { module test {
service MyTestService : XMyTest;
}; }; };

#endif
</source>
* '''org/openoffice/test/XMyTest.idl''' the test interface definition
<source lang="idl">
/*
* XMyTest.idl
*
* Created on 11.09.2006 - 17:42:17
*
*/

#ifndef _org_openoffice_test_XMyTest_
#define _org_openoffice_test_XMyTest_

#include <com/sun/star/uno/XInterface.idl>

module org { module openoffice { module test {
interface XMyTest {

string helloWorld([in] string sMessage);
raises ( com::sun::star::lang::IllegalArgumentException );
};
}; }; };

#endif
</source>
* '''org/openoffice/test/TestComponentImpl.java''' the generated code skeleton where all selected services and interface are implemented by defualt plus some UNO component base interfaces, so that the newly generated project can be built and the extension can be deployed directly.
<source lang="java">
package org.openoffice.test;

import com.sun.star.uno.UnoRuntime;
import com.sun.star.uno.XComponentContext;
import com.sun.star.lib.uno.helper.Factory;
import com.sun.star.lang.XSingleComponentFactory;
import com.sun.star.registry.XRegistryKey;
import com.sun.star.lib.uno.helper.WeakBase;

public final class TestComponentImpl extends WeakBase
implements com.sun.star.lang.XServiceInfo,
org.openoffice.test.XMyTest
{
private final XComponentContext m_xContext;
private static final String m_implementationName = TestComponentImpl.class.getName();
private static final String[] m_serviceNames = {
"org.openoffice.test.MyTestService" };

public TestComponentImpl( XComponentContext context )
{
m_xContext = context;
}

public static XSingleComponentFactory __getComponentFactory(String sImplementationName ) {
XSingleComponentFactory xFactory = null;

if ( sImplementationName.equals( m_implementationName ) )
xFactory = Factory.createComponentFactory(TestComponentImpl.class, m_serviceNames);
return xFactory;
}

public static boolean __writeRegistryServiceInfo(XRegistryKey xRegistryKey ) {
return Factory.writeRegistryServiceInfo(m_implementationName,
m_serviceNames,
xRegistryKey);
}

// com.sun.star.lang.XServiceInfo:
public String getImplementationName() {
return m_implementationName;
}

public boolean supportsService( String sService ) {
int len = m_serviceNames.length;

for( int i=0; i < len; i++) {
if (sService.equals(m_serviceNames[i]))
return true;
}
return false;
}

public String[] getSupportedServiceNames() {
return m_serviceNames;
}

// org.openoffice.test.XMyTest:
public String helloWorld(String sMessage) throws com.sun.star.lang.IllegalArgumentException
{
// TODO !!!
// Exchange the default return implementation.
// NOTE: Default initialized polymorphic structs can cause problems
// because of missing default initialization of primitive types of
// some C++ compilers or different Any initialization in Java and C++
// polymorphic structs.
return "";
}

}
</source>

= Result Use Example : OOoBasic Macro Call =

For using the previous skeleton for an OOoBasic service call, we only have to alter the last method helloWorld and redeploy the oxt extension
<source lang="java">
// org.openoffice.test.XMyTest:
public String helloWorld(String message)
{
String response = "Hello " + message;
return response;
}
</source>

Then, opening a new OpenOffice.org, your component is available for any macro you may need. It is seen as any legacy service and is manipulated the same way. Even introspection is available, letting you verify that all your properties and methods are available, as the xRay call can show.
<source lang="oobas">
sub TestHelloWorld()
' Create the new UNO service
myService = createUNOService("org.openoffice.test.MyTestService")
' The new service with its properties & methods is available
msgbox myService.helloWorld ("Laurent")
' It is also available through Xray introspection
xRay myService
end sub
</source>
{| border="0"
|-
| [[Image:hello_testing_netbeans.png|center]]
| [[Image:xray_helloworld_netbeans.png|center]]
|}

= See also =
* Daniel Bölzle's tutorial : [[Uno/Cpp/Tutorials/component_tutorial|Writing a simple UNO component]]
* [[Documentation/DevGuide/WritingUNO/Writing_UNO_Components|Writing UNO Components]] in Developer's Guide
* [[Constructing_Components|Constructing Components in C++]]
* [[Extensions_Packager|Extensions Packager]] (BasicAddonBuilder from [mailto:paolomantovani@openoffice.org Paolo Mantovani])
* [[BASIC/UNO_Object_Browser|BASIC UNO Object Browser]] : You can see the corresponding code as a complex component.
* [[API/Samples/Java/Office/MinimalComponent|Minimal Java Component]]

[[Category:Uno]]
[[Category:Development]]
[[Category:Extensions]]
[[Category:API]]

Documentation/DevGuide/Scripting/Writing Macros

2010-03-27T06:09:39Z

Newacct:

{{Documentation/DevGuide/ScriptingTOC
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Scripting/Macro Recording
|NextPage=Documentation/DevGuide/Scripting/How the Scripting Framework Works
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Scripting/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Writing Macros}}
__NOTOC__
=== The HelloWorld macro ===

When the user creates a new macro in BeanShell or JavaScript, the default content of the macro is the HelloWorld. Here is what the code looks like for BeanShell:

<source lang="java">
import com.sun.star.uno.UnoRuntime;

import com.sun.star.text.XTextDocument;
import com.sun.star.text.XText;
import com.sun.star.text.XTextRange;

oDoc = XSCRIPTCONTEXT.getDocument();
xTextDoc = (XTextDocument) UnoRuntime.queryInterface(XTextDocument.class,oDoc);
xText = xTextDoc.getText();
xTextRange = xText.getEnd();
xTextRange.setString( "Hello World (in BeanShell)" );

// BeanShell OpenOffice.org scripts should always return 0
return 0;
</source>

As BeanShell accepts typeless variables, the queryInterface instructions can be simplified.

Like OpenOffice.org Basic, BeanShell interprets pairs of get and set methods at UNO objects as object properties if they follow this pattern:

SomeType getSomeProperty()
void setSomeProperty(SomeType aValue)

Using these facilities the above example can be simplified:

<source lang="java">
import com.sun.star.uno.UnoRuntime;

import com.sun.star.text.XTextDocument;
import com.sun.star.text.XText;
import com.sun.star.text.XTextRange;

oDoc = XSCRIPTCONTEXT.Document;
xTextDoc = UnoRuntime.queryInterface(XTextDocument.class,oDoc);
xText = xTextDoc.Text;
xTextRange = xText.End;
xTextRange.String = "Hello World (in BeanShell)";

// BeanShell OpenOffice.org scripts should always return 0
return 0;
</source>

Here is the same code in JavaScript:
<source lang="javascript">
importClass(Packages.com.sun.star.uno.UnoRuntime);
importClass(Packages.com.sun.star.text.XTextDocument);
importClass(Packages.com.sun.star.text.XText);
importClass(Packages.com.sun.star.text.XTextRange);

oDoc = XSCRIPTCONTEXT.getDocument();
xTextDoc = UnoRuntime.queryInterface(XTextDocument,oDoc);
xText = xTextDoc.getText();
xTextRange = xText.getEnd();
xTextRange.setString( "Hello World (in JavaScript)" );
</source>
Here is the code for HelloWorld in Java:
<source lang="java">
import com.sun.star.uno.UnoRuntime;
import com.sun.star.frame.XModel;
import com.sun.star.text.XTextDocument;
import com.sun.star.text.XTextRange;
import com.sun.star.text.XText;
import com.sun.star.script.provider.XScriptContext;

public class HelloWorld {
public static void printHW(XScriptContext xScriptContext)
{
XModel xDocModel = xScriptContext.getDocument();

// getting the text document object
XTextDocument xtextdocument = (XTextDocument) UnoRuntime.queryInterface(
XTextDocument.class, xDocModel);

XText xText = xtextdocument.getText();
XTextRange xTextRange = xText.getEnd();
xTextRange.setString( "Hello World (in Java)" );
}
}
</source>
The table below outlines some of the features of macro development in the different languages:

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
!Language
!Interpreted
!Typeless
!Editor
!Debugger
|-
|BeanShell
|Yes
|Yes
|Yes
|No
|-
|JavaScript
|Yes
|Yes
|Yes
|Yes
|-
|Java
|No
|No
|No
|No
|}

{{Documentation/Note|Instructions on compiling and deploying Java macros can be found later in this chapter.}}

=== Using the {{PRODUCTNAME}} API from macros ===

All BeanShell, JavaScript and Java macros are supplied with a variable of type <idl>com.sun.star.script.provider.XScriptContext</idl> which can be used to access the {{PRODUCTNAME}} API. This type has three methods:

* <idl>com.sun.star.frame.XModel</idl> <code>getDocument( )</code>
:Returns the <code>XModel</code> interface of the document for which the macro was invoked (see [[Documentation/DevGuide/OfficeDev/Using the Component Framework|Using the Component Framework]])
* <idl>com.sun.star.frame.XDesktop</idl> <code>getDesktop( )</code>
:Returns the <code>XDesktop</code> interface for the application which can be used to access open document, and load documents (see [[Documentation/DevGuide/OfficeDev/Using the Desktop|Using the Desktop]])
* <idl>com.sun.star.uno.XComponentContext</idl> <code>getComponentContext( )</code>
:Returns the <code>XComponentContext</code> interface which is used to create instances of services (see [[Documentation/DevGuide/ProUNO/Service Manager and Component Context|Service Manager and Component Context]])

Depending on the language the macro accesses the <code>XScriptContext</code> type in different ways:

* '''BeanShell''': Using the global variable <code>XSCRIPTCONTEXT</code>
oDoc = XSCRIPTCONTEXT.getDocument();

* '''JavaScript''': Using the global variable <code>XSCRIPTCONTEXT</code>
oDoc = XSCRIPTCONTEXT.getDocument();

* '''Java''': The first parameter passed to the macro method is always of type <code>XScriptContext</code>
Xmodel xDocModel = xScriptContext.getDocument();

=== Handling arguments passed to macros ===

In certain cases arguments may be passed to macros, for example, when a macro is assigned to a button in a document. In this case the arguments are passed to the macro as follows:

* '''BeanShell''': In the global <code>Object[]</code> variable <code>ARGUMENTS</code>
event = (ActionEvent) ARGUMENTS[0];

* '''JavaScript''': In the global <code>Object[]</code> variable <code>ARGUMENTS</code>
event = ARGUMENTS[0];

* '''Java''': The arguments are passed as an <code>Object[]</code> in the second parameter to the macro method
public void handleButtonPress(
XScriptContext xScriptContext, Object[] args)

Each of the arguments in the <code>Object[]</code> are of the UNO type Any. For more information on how the Any type is used in Java see [[Documentation/DevGuide/ProUNO/Java/Type Mappings|Type Mappings]].

The ButtonPressHandler macros in the Highlight library of a {{PRODUCTNAME}} installation show how a macro can handle arguments.

=== Creating dialogs from macros ===

Dialogs which have been built in the Dialog Editor can be loaded by macros using the <idl>com.sun.star.awt.XDialogProvider</idl> API. The <code>XDialogProvider</code> interface has one method <code>createDialog()</code> which takes a string as a parameter. This string is the URL to the dialog. The URL is formed as follows:

vnd.sun.star.script:DIALOGREF?location=[application|document]

where <code>DIALOGREF</code> is the name of the dialog that you want to create, and location is either application or document depending on where the dialog is stored.

For example if you wanted to load dialog called MyDialog, which is in a Dialog Library called MyDialogLibrary in the {{PRODUCTNAME}} dialogs area of your installation then the URL would be:

vnd.sun.star.script:MyDialogLibrary.MyDialog?location=application

If you wanted to load a dialog called MyDocumentDialog which in a library called MyDocumentLibrary which is located in a document then the URL would be:

vnd.sun.star.script:MyDocumentLibrary.MyDocumentDialog?location=document

The following code shows how to create a dialog from a Java macro:
<source lang="java">
public XDialog getDialog(XScriptContext context)
{
XDialog theDialog;

// We must pass the XModel of the current document when creating a DialogProvider object
Object[] args = { context.getDocument() };

Object obj;
try {
obj = xmcf.createInstanceWithArgumentsAndContext(
"com.sun.star.awt.DialogProvider", args, context.getComponentContext());
}
catch (com.sun.star.uno.Exception e) {
System.err.println("Error getting DialogProvider object");
return null;
}

XDialogProvider xDialogProvider = (XDialogProvider)
UnoRuntime.queryInterface(XDialogProvider.class, obj);

// Got DialogProvider, now get dialog
try {
theDialog = xDialogProvider.createDialog(
"vnd.sun.star.script:MyDialogLibrary.MyDialog?location=application");
}
catch (java.lang.Exception e) {
System.err.println("Got exception on first creating dialog: " + e.getMessage());
}
return theDialog;
}
</source>
=== Compiling and Deploying Java macros ===

Because Java is a compiled language it is not possible to execute Java source code as a macro directly from within {{PRODUCTNAME}}. The code must first be compiled and then deployed within a {{PRODUCTNAME}} installation or document. The following steps show how to create a Java macro using the HelloWorld example code:

* Create a ''HelloWorld'' directory for your macro
* Create a ''HelloWorld.java'' file using the HelloWorld source code
* Compile the ''HelloWorld.java'' file. The following jar files from the ''program/classes'' directory of a {{PRODUCTNAME}} installation must be in the classpath: ''ridl.jar'', ''unoil.jar'', ''jurt.jar''
* Create a ''HelloWorld.jar'' file containing the ''HelloWorld.class'' file
* Create a ''parcel-descriptor.xml'' file for your macro
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<parcel language="Java" xmlns:parcel="scripting.dtd">
<script language="Java">
<locale lang="en">
<displayname value="HelloWorld"/>
<description>
Prints "Hello World".
</description>
</locale>
<functionname value="HelloWorld.printHW"/>
<logicalname value="HelloWorld.printHW"/>
<languagedepprops>
<prop name="classpath" value="HelloWorld.jar"/>
</languagedepprops>
</script>
</parcel>
</source>
The ''parcel-descriptor.xml'' file is used by the Scripting Framework to find macros. The functionname element indicates the name of the Java method which should be executed as a macro. The classpath element can be used to indicate any jar or class files which are used by the macro. If the classpath element is not included, then the directory in which the ''parcel-desciptor.xml'' file is found and any jar files in that directory will be used as the classpath. The necessary Java UNO classes are available automatically.

* Copy the HelloWorld directory into the ''share/Scripts/java'' directory of a {{PRODUCTNAME}} installation or into the ''user/Scripts/java'' directory of a user installation. If you want to deploy the macro to a document you need to place it in a ''Scripts/java'' directory within the document zip file.
* If {{PRODUCTNAME}} is running, you will need to restart it in order for the macro to appear in the Macro Selector dialog.

{{Documentation/Note|The ''parcel-descriptor.xml'' file is also used to detect BeanShell and JavaScript macros. It is created automatically when creating macros using the Organizer dialogs for BeanShell and JavaScript.}}

{{PDL1}}

[[Category:Documentation/Developer's Guide/Scripting]]

ES PyUNOServer

2010-03-14T07:39:23Z

Newacct:

El PyUNOServer es un script el cual pretende funcionar como un servidor para OpenOffice.org donde este pueda emitir y recibir llamadas usando XMLRPC. Esto quiere decir que puede obtener informacion desde otras aplicacion en una arquitectura usada por Webservices.

El zip contiene tres archivos:
* PyUNOServerV2.py - es el script de Python
* PyUNOServerV2.pyc - version compilada
* PyUNOServer.sh2 - script para conectar al servicio

<pre><nowiki>[python]
# -*- coding: iso-8859-1 -*-
#
# pyUnoServer - version 2.0
#
# (C) 2005 ECWeb Ingenieria y Desarrollo - http://www.ecweb.cl/
# Written by:
# - Jose Antonio Akel <jakel@NOSPAMecweb.cl>
# - Hector Vergara <hector@NOSPAMecweb.cl>
# - Luis Gonzalez Miranda <lgm@NOSPAMecweb.cl>
#
# This program is freely distributable per the following license:
#
# Permission to use, copy, modify, and distribute this software and its
# documentation for any purpose and without fee is hereby granted,
# provided that the above copyright notice appears in all copies and that
# both that copyright notice and this permission notice appear in
# supporting documentation.
#
# I DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL I
# BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY
# DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
# WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
# ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
# SOFTWARE.

“"”
This program implements a XMLRPC gateway to Openoffice's Spreadsheet Calculator,
allowing external programs to exchange data with spreadsheets.
“"”

from SimpleXMLRPCServer import SimpleXMLRPCServer, SimpleXMLRPCRequestHandler
import os
import uno
import sys
import time
import logging
import urllib

class PyUNOServer(SimpleXMLRPCServer):

def _dispatch(self, method, params):
try:
func = getattr(self, '' + method)
except:
self.logger.error("El Metodo '"+method+"' no esta soportado!")
raise Exception('method "%s" is not supported' % method)
else:
try:
ret = func(*params)
self.logger.info("Llamada: "+str(method)+str(params)+" | Retorno: "+str(ret))
return ret
except:
self.logger.info("Llamada: "+str(method)+str(params))
self.logger.error("Error: "+str(sys.exc_type)+":"+str(sys.exc_value))
ef init(self):
"""
This method starts an Openoffice session and initializes the XMLRPC server
"""

#Creo algunas constantes de utilidad
self.EMPTY = uno.Enum("com.sun.star.table.CellContentType", "EMPTY")
self.TEXT = uno.Enum("com.sun.star.table.CellContentType", "TEXT")
self.FORMULA = uno.Enum("com.sun.star.table.CellContentType", "FORMULA")
self.VALUE = uno.Enum("com.sun.star.table.CellContentType", "VALUE")
# Creo un Logger
self.logger = logging.getLogger('pyUnoServer')
hdlr = logging.FileHandler('./pyUnoServer.log')
formatter = logging.Formatter('%(asctime)s %(levelname)s -- %(message)s')
hdlr.setFormatter(formatter)
self.logger.addHandler(hdlr)
self.logger.setLevel(logging.INFO)
self.sessions = []
self.sessionSerial = 0
# Echo a correr el OpenOffice Calc obteniendo su PID
self.PID = os.spawnlp(os.P_NOWAIT,"/usr/bin/oocalc","","-accept=socket,host=localhost,port=2002;urp;")

self.logger.info("OOCalc Iniciado con el PID "+str(self.PID))
while 1:
try:
localContext = uno.getComponentContext()
resolver = localContext.ServiceManager.createInstanceWithContext("com.sun.star.bridge.UnoUrlResolver", localContext )
smgr = resolver.resolve( "uno:socket,host=localhost,port=2002;urp;StarOffice.ServiceManager" )
remoteContext = smgr.getPropertyValue( "DefaultContext" )
self.desktop = smgr.createInstanceWithContext( "com.sun.star.frame.Desktop",remoteContext)
self.logger.info("Sistema conectado al socket de UNO")
break
except:
time.sleep(0.5)
ef openSession(self, session):
"""
This method opens a new session.
Sample usage from PHP:
- $sessionString is your a session ID provided by your program):
$openSession = array( new XML_RPC_VALUE($sessionString, "string"));
$sessionID = queryXMLRPC($client, "openSession", $openSession);
return $sessionID;
"""
currentSerial = -1
for i in range(0,len(self.sessions)):
if self.sessions[i][0] == session:
currentSerial = i
break

if currentSerial == -1:
self.sessions.append([session,[]])
currentSerial = len(self.sessions)-1
return currentSerial

ef getSessions(self):
return self.sessions
ef openBook(self, session, bookPath):
"""
This method opens a new Openoffice spreadsheet book.
Sample usage from PHP:
- $sessionID is the session's ID returned by openSession()
- $path is the path to the book in the server's filesystem
$openBookQuery = array( new XML_RPC_VALUE($sessionID, "int"), new XML_RPC_VALUE($path,"string") );
$bookID = queryXMLRPC($client, "openBook", $openBookQuery);
return $bookID;
"""
currentSerial = session
bookPath = bookPath.strip()
print bookPath
exists = os.path.exists(bookPath)
if exists == False:
raise Exception('El libro %s no existe', bookPath)
else:
self.logger.info("se ha encontrado el libro!")

currentBook = -1

for i in range(0, len(self.sessions[currentSerial][1])):
try:
book = self.sessions[currentSerial][1][i]

bookname = book[0]
bookhandler = book[1]
bookmodtime = book[2]

if bookname == bookPath:
modtime = os.path.getmtime(bookPath)
if (modtime > bookmodtime):
book[1].dispose()
self.sessions[currentSerial][1].remove(book)
else:
currentBook = i
break
except:
self.logger.error("El libro "+currentBook+" no existe!")

if (currentBook < 0 ):
handler = self.desktop.loadComponentFromURL( "file://" + bookPath ,"_blank",0,())
if(handler == None):
raise Exception('El libro no existe o tiene caracteres extraños...')
modtime = os.path.getmtime(bookPath)

estruct = [bookPath,handler,modtime]
self.sessions[currentSerial][1].append(estruct)
currentBook = len(self.sessions[currentSerial][1])-1

return currentBook
ef closeBook(self, sessionID, bookID):

books = self.sessions[sessionID][1]

#esto cierra el documento. Parece Cerdo, pero segun la documentcion, asi es
books[bookID][1].dispose()
self.sessions[sessionID][1].remove(books[bookID])

return 1
ef getBookSheets(self, sessionID, bookID):
"""
This method return an array with the book's worksheets.
Sample usage from PHP:
- $sessionID is the session's ID returned by openSession()
- $bookID is the book's ID returned by openBook()
$sheetsQuery = array( new XML_RPC_VALUE($sessionID, "int"), new XML_RPC_VALUE($bookID, "int") );
$sheets = queryXMLRPC($client, "getBookSheets" , $sheetsQuery);
return $sheets;
"""

sheets = self.sessions[sessionID][1][bookID][1].getSheets().createEnumeration()

container = []
while(sheets.hasMoreElements()):
currentSheet = sheets.nextElement()
container.append(currentSheet.getName().encode("UTF-8"))

return container
ef getCellValue (self,sheet,x,y):
cell = sheet.getCellByPosition(x,y)
cellType = cell.getType()
if cellType == self.TEXT :
data = cell.getString().encode("UTF-8")
if data == None:
return ""
return data.encode("UTF-8")

if cellType == self.FORMULA or cellType == self.VALUE :
data = cell.getValue()
if data == None:
return 0
return cell.getValue()
if cellType == self.EMPTY :
return ""
ef getCell(self, session, book, sheet, x, y):
"""
This method returns the content of a cell.
Sample usage from PHP:
- $sessionID is the session's ID returned by openSession()
- $bookID is the book's ID returned by openBook()
- $sheet is the sheet's ID as returned by getBookSheets()
$query = array(
new XML_RPC_Value($sessionID, "int"),
new XML_RPC_VALUE($bookID, "int"),
new XML_RPC_VALUE($sheet, "int"),
new XML_RPC_Value($x, "int"),
new XML_RPC_Value($y, "string")
);
$result = queryXMLRPC($client, "getCell", $query);
return $result;
"""
sheetref = self.sessions[session][1][book][1].getSheets().getByIndex(sheet)
valor = self.getCellValue(sheetref,x,y)
return valor

ef setCell(self,session,book,sheet,x,y,value):
"""
This method sets the content of a cell.
Sample usage from PHP:
- $sessionID is the session's ID returned by openSession()
- $bookID is the book's ID returned by openBook()
- $sheet is the sheet's ID as returned by getBookSheets()
$query = array(
new XML_RPC_Value($sessionID, "int"),
new XML_RPC_VALUE($bookID, "int"),
new XML_RPC_VALUE($sheet, "int"),
new XML_RPC_Value($x, "int"),
new XML_RPC_Value($y, "int"),
new XML_RPC_Value($value, "string")
);
$result = queryXMLRPC($client, "setCell", $query);
return $result;
"""

bookObject = self.sessions[session][1][book][1]
cell = bookObject.getSheets().getByIndex(sheet).getCellByPosition(x,y)
cell.setValue(value)
return 1
en que cambiara todo? mmm...
ef massiveSetCell(self, data):
for valores in data:
session,sheetid,x,y,valor = valores.split("|")
code = self.setCell(self.trim(session),self.trim(sheetid),self.trim(x),self.trim(y),valor)
if code < 0:
return code
return 1
ef getSheetPreview(self,session,book,sheet):
sheet = self.sessions[session][1][book][1].getSheets().getByIndex(sheet)
range = sheet.getCellRangeByPosition(0,0,8,23).getDataArray()
return range

ef trim(self, cadena):
return cadena.strip()

server = PyUNOServer2)

server.init() server.logger.info(“Servicio Inicializado…”)

try:
erver.serve_forever()

except KeyboardInterrupt:
erver.logger.info("Cerrando el socket...")
erver.server_close()
s.kill(server.PID,1)
erver.logger.info("Socket cerrado.")</nowiki></pre>

==startPyUnoServer.sh2==
<pre><nowiki>[bash]
#!/bin/bash
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib/openoffice/program/
export PYTHONPATH=$PYTHONPATH:/usr/lib/openoffice/program
export DISPLAY=localhost:1
echo "Logging en pyUnoServer.log"
python pyUnoServerV2.py
echo "CHAO!"
</nowiki></pre>
[[Category:ES]]

AODL wishlist

2010-02-26T23:09:13Z

Newacct: /* Bugfix */

In this article, you can add descriptions of features you would like to see in [[AODL|AODL]]. This can serve as a source of inspiration for developers and contributers. Hopefully, these might be implemented during the [[Summer of Code 2007#ODF_Toolkit|Summer of Code 2007]] work on this project

==Bugfix==
I have fixed a bug on loading a existing table who have some empty cells (OpenOffice creates here a attribute "table:number-columns-repeated" who declares the number of copies of this cell.

Here is the sourcecode to fix the problem:

'''Add this to the Cell data object:'''

<pre>
///
/// Gets or sets the number of columns repeated.
///
/// The number of columns repeated.
public int NumberOfColumnsRepeated { get; set; }
</pre>

'''The method CreateTableCell()'''
<pre>
...
...
...

//Create a new Cel
Cell cell = new Cell(this._document, node);
IContentCollection iColl = new IContentCollection();
//Recieve CellStyle
IStyle cellStyle = this._document.Styles.GetStyleByName(cell.StyleName);

if(cellStyle != null)
{
int i=0;
cell.Style = cellStyle;
if(cellStyle.StyleName == "ce244")
i=1;
}
//No need for a warning

// this is the new code:::

// check for thew "table:number-columns-repeated" attribute
int repeating = 0;

foreach(XmlAttribute attr in node.Attributes) {
if(attr.Name == "table:number-columns-repeated") {
int.TryParse(attr.Value, out repeating);
cell.NumberOfColumnsRepeated = repeating;
}
}

// :::end of new code

//Create the cells content
foreach(XmlNode nodeChild in cell.Node.ChildNodes)
{
IContent iContent = this.CreateContent(nodeChild);

if(iContent != null)
{
iColl.Add(iContent);
}
else if(this.OnWarning != null)
{
AODLWarning warning = new AODLWarning("Couldn't create IContent from a table cell.");
warning.InMethod = AODLException.GetExceptionSourceInfo(new StackFrame(1, true));
warning.Node = nodeChild;
this.OnWarning(warning);
}
}

cell.Node.InnerXml = "";

foreach(IContent iContent in iColl)
cell.Content.Add(iContent);
return cell;

...
...
...
</cite>

'''The method CreateTableRow()'''
<pre>
...
...
...

foreach(IContent iContent in iColl)
{
if(iContent is Cell)
{

// this is the new code:::
// new way
Cell cell = (Cell)iContent;
cell.Row = row;

row.CellCollection.Add(cell);

for(int i = 1; i < cell.NumberOfColumnsRepeated; i++) {
XmlNode copyNode = cell.Node.CloneNode(true);
copyNode.Attributes.RemoveAll();
row.CellCollection.Add(this.CreateTableCell(copyNode));
}

// :::end of new code

// old way ...
//( (Cell)iContent ).Row = row;
//row.CellCollection.Add(cell);
}
else if(iContent is CellSpan)
{
((CellSpan)iContent).Row = row;
row.CellSpanCollection.Add(iContent as CellSpan);
}
else if(this.OnWarning != null)
{
AODLWarning warning = new AODLWarning("Couldn't create IContent from a row node. Content is unknown table row content!");
warning.InMethod = AODLException.GetExceptionSourceInfo(new StackFrame(1, true));
warning.Node = iContent.Node;
this.OnWarning(warning);
}
}

...
...
...
</pre>

==Bugfix==
'''include bugfix posted on sourceforge.net'''

several month ago i had a problem with aodl and large tables.. i posted the bug, testcode and the bugfix a few days later on the sourceforge bugtracker. please fix this big bug!

i haven't found a email-adress to which i could direct mail this request, but i hope someone will read this text and fix the bug! THX! [[User:Artemis1121|Artemis1121]] 09:49, 17 October 2007 (CEST)

==Styles==

'''Font by String'''

Allow indicating and using fonts by string, such as "Broadway BT", rather than FontFamilies.BroadwayBT;

Otherwise, when I would try to use a typeface not included in the standard installations, such as "Gentium" or "DejaVu Sans", these would never be available under the hardcoded system.

'''Table Cell Widths'''
Allow define of cell widths for individual cells or columns.

==Graphics==
'''Captions'''
Is there a way to add a caption to a Frame that has a graphic in it? I can simply add text below a figure, but I would like the captions to be sequences so that I could then build a table of contents. Below is a snippet of xml from an ODT content.xml file that shows what I need (written from OpenOffice). A little bit from the end is a text: sequence element. How do I add this using AODL? The graphics are no problem it's just the sequence that I'm lost on.

'''SVG'''
Work with SVG Import to allow runtime SVG insertion.

==AutoText==
My document assembly strategy relies heavily upon use of AutoText entries. Please implement Autotext features.

==Master Documents==
Easy insertion of smaller documents into Master documents without XmlDoc.ImportNode
[[category:Summer of Code 2007]][[category:AODL]]

==Temporary Files==
Please insert a possibility to change the path whitch is used for the temporary extraction of the ODF-Files. Maybe it can be set to the systemwide Temp-Directory.

API/Tutorials/PDF export

2010-02-26T20:24:07Z

Newacct:

PDF export is an important and useful feature of OpenOffice.org that can completely be automatized using OpenOffice.org API, quite every aspect of exporting to PDF in the graphical user interface is also available for programming: documents can be exported directly with default settings just passing the proper filter name and an URL, every option the user can set in the GUI can also be set programmatically in the filter options, also these settings are configurable via the API (they can be accessed, changed, or reset to their default values), and even the options dialog for exporting to PDF can be used through pure API calls.

This tutorial will show how to use OpenOffice.org API to export documents to PDF. The reader should have at least a basic knowledge about handling office documents (how to load and store a document), and should also know how to access OpenOffice.org configuration.

This tutorial also aims to provide a full up-to-date documentation about the PDF export filter options, as these specific properties are usually not documented and only available in the core OpenOffice.org source code (thus not accessible for developers aiming to work only with its API).

The sources for this tutorial can be found [http://api.openoffice.org here]. They are not intended to provide a ready-to-use PDF export application, but to give you a tool for doing your own experiments.

= PDF Export basics =

A document can be exported by saving it to a different location and using a special filter capable to write the document to the desired format. In the API, documents are storable through their interface <idl>com.sun.star.frame.XStorable</idl>, as discussed in detail in [[Documentation/DevGuide/OfficeDev/Storing Documents|Developer's Guide - Office Development - Storing Documents]].

For exporting, besides the location (in URL notation) where the exported document is to be stored, a filter name must be passed to <code>XStorable.storeAsURL()</code> and <code>XStorable.storeToURL()</code>. The property needed for this purpose is the string argument <idlm>com.sun.star.document.MediaDescriptor:FilterName</idlm> that takes the name of a filter already known by OpenOffice.org.

In the simplest case, all you need for exporting to PDF is the URL where you want to export the document and the filter name; this way, the document will be exported using the current PDF export settings (the ones used the last time, or the default values stipulated by the filter configuration, if this is first time).

The following code shows the basic procedure:

<source lang="java">

XComponent xComponent = null;
// create a new Writer document using a helper
xComponent = Helper.createNewDoc(m_xContext, "swriter");

// access its XTextDocument interface
XTextDocument xTextDocument = (XTextDocument) UnoRuntime.queryInterface(
XTextDocument.class, xComponent);

// access the text body and set a string
XText xText = xTextDocument.getText();
xText.setString("Simple PDF export demo.");

// XStorable to store the document
XStorable xStorable = (XStorable) UnoRuntime.queryInterface(
XStorable.class, xComponent);

// XStorable.storeToURL() expects an URL telling where to store the document
// and an array of PropertyValue indicating how to store it

// URL = use helper method to get the home directory
String sURL = Helper.getHomeDir(m_xContext) + "/Simple_PDF_EXPORT_demo.pdf";

// Exporting to PDF consists of giving the proper
// filter name in the property "FilterName"
// With only this, the document will be exported
// using the existing PDF export settings
// (the one used the last time, or the default if the first time)
PropertyValue[] aMediaDescriptor = new PropertyValue[1];
aMediaDescriptor[0] = new PropertyValue();
aMediaDescriptor[0].Name = "FilterName";
aMediaDescriptor[0].Value = "writer_pdf_Export";

xStorable.storeToURL(sURL, aMediaDescriptor);

</source>

As the code shows, <code>XStorable.storeToURL()</code> expects an URL as first parameter, and an array of <idl>com.sun.star.beans.PropertyValue</idl> structs as second parameter, which implements the <idl>com.sun.star.document.MediaDescriptor</idl> service, consisting of property definitions. The media descriptor is used for loading/importing and saving/exporting documents, please refer to the [[Documentation/DevGuide/OfficeDev/Handling_Documents#MediaDescriptor|Developer's Guide]] for a detailed explanation. In this case, it includes only the struct for the <idlm>com.sun.star.document.MediaDescriptor:FilterName</idlm>, indicating the name of the filter for exporting Writer documents to PDF.

You can fully customize the PDF export process by adding another <code>PropertyValue</code> struct to the MediaDescriptor array: <idlm>com.sun.star.document.MediaDescriptor:FilterData</idlm>. This parameter is used to pass properties specific for a special filter type. In the case of the PDF export filter, another array of <code>PropertyValue</code> structs is expected.

In the next section, we will describe the complete list of specific properties available at the present for the PDF export filter.

= PDF Export filter data =

The following tables contain all the properties available in the PDF export filter implementation in OpenOffice.org 2.4. You must be aware of the fact that they are ''implementation specific'', so you may not find all of them in previous versions (nor expect that they remain the same in the future).

The tables follow the order of the PDF Export dialog tab pages, so that you can easily understand their meaning just comparing them with this dialog.

Notes:

* The '''Description''' column contains descriptions taken mainly from the PDF Export Dialog configuration, found in <code><nowiki><</nowiki>opt/openoffice.org2.4<nowiki>></nowiki>/share/registry/schema/org/openoffice/Office/Common.xcs</code>
* The '''Type''' column refers to the UNO IDL data types (see [[Documentation/DevGuide/ProUNO/Simple Types | Developer's Guide - Professional UNO - Simple Types]]), not the OpenOffice.org Registry data types (see [[Documentation/DevGuide/Config/Object Model | Developer's Guide - Configuration Management - Object Model]] and [http://util.openoffice.org/common/configuration/oor-document-format.html#RegistryOM OpenOffice.org Registry Format - Registry Object Model]). For the '''mapping''' refer to [http://util.openoffice.org/common/configuration/api_spec.html#Types%20Objects%20and%20Values Configuration API Overview - Types, Objects and Values].
* The '''Default value''' column contains the default value as indicated in the PDF Export Dialog configuration mentioned above.

== General properties ==

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
| <center>'''Property Name'''</center>
| <center>'''Description'''</center>
| <center>'''Type'''</center>
| <center>'''Default value'''</center>

|-
| <code>PageRange</code>
| If this property is set, it indicates the range of pages to be printed.

If you want to print all the pages, leave this property unset.

If you want to export a selection, leave this property unset, setting only the property '''Selection'''.
| <center>string</center>
| <center>empty</center>

<center>(all pages are printed)</center>

|-
| <code>Selection</code>
| An '''any''' corresponding to the current selection in the document.
| <center>any</center>
|

|-
| <code>UseLosslessCompression</code>
| Specifies if graphics are exported to PDF using a lossless compression eg. '''PNG''' or if they are compressed using the '''JPEG''' format.
| <center>boolean</center>
| <center>false</center>

|-
| <code>Quality</code>
| Specifies quality of the JPG export. A higher value results in higher quality and file.

''Minimum inclusive value'': 1. Represents lowest value that can be used. The lower the value, the less good is the compression quality and the bigger is be the file size.

''Maximum inclusive value'':100. Represents highest value that can be used. The higher the value, the better is the compression quality and the smaller is the file size.
| <center>long</center>
| <center>90</center>

|-
| <code>ReduceImageResolution</code>
| Specifies if the resolution of each image is reduced to the resolution specified by the property MaxImageResolution.
| <center>boolean</center>
| <center>false</center>

|-
| <code>MaxImageResolution</code>
| If the property ReduceImageResolution is set to true all images will be reduced to the given value in DPI.

Posible values:

* 75
* 150
* 300
* 600
* 1200

| <center>long</center>
| <center>300</center>

|-
| <code>SelectPdfVersion</code>
| Specifies the version of PDF to emit.

Possible values:

* 0 = PDF 1.4 (default selection).
* 1 = PDF/A-1 (ISO 19005-1:2005)

| <center>long</center>
| <center>0</center>

|-
| <code>UseTaggedPDF</code>
| Determines if PDF are created by using special tags also known as Tagged PDF.
| <center>boolean</center>
| <center>false</center>

|-
| <code>ExportFormFields</code>
| Specifies whether form fields are exported as widgets or only their fixed print representation is exported.
| <center>boolean</center>
| <center>true</center>

|-
| <code>FormsType</code>
| Specifies the submitted format of a PDF form.

Possible values:

* 0= Specifies that forms type '''FDF''' is used.
* 1= Specifies that forms type '''PDF''' is used.
* 2= Specifies that forms type '''HTML''' is used.
* 3= Specifies that forms type '''XML''' is used.

| <center>long</center>
| <center>0</center>

|-
| <code>ExportBookmarks</code>
| Specifies if bookmarks are exported to PDF.
| <center>boolean</center>
| <center>true</center>

|-
| <code>ExportNotes</code>
| Specifies if notes are exported to PDF.
| <center>boolean</center>
| <center>false</center>

|-
| <code>ExportNotesPages</code>
| Specifies if notes pages are exported to PDF. (Notes pages are available in '''Impress''' documents only).
| <center>boolean</center>
| <center>false</center>

|-
| <code>IsSkipEmptyPages</code>
| Specifies that automatically inserted empty pages are suppressed. This option is active only if storing Writer documents.
| <center>boolean</center>
| <center>false</center>

|-
| <code>IsAddStream</code>
| Specifies that a stream is inserted to the PDF file which contains the original document for archiving purposes.
| <center>boolean</center>
| <center>false</center>

|}

== Initial view ==

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
! <center>Property Name</center>
! <center>Description</center>
! <center>Type</center>
! <center>Default value</center>

|-
| <code>InitialView</code>
| Specifies how the PDF document should be displayed when opened.

Possible values:

* 0= Select the default viewer mode, neither outlines or thumbnails.
* 1= The document is opened with outline pane opened
* 2= The document is opened with thumbnail pane opened

| <center>long</center>
| <center>0</center>

|-
| <code>InitialPage</code>
| Specifies the page on which a PDF document should be opened in the viewer application.
| <center>long</center>
| <center>1</center>

|-
| <code>Magnification</code>
| Specifies the action to be performed when the PDF document is opened.

Possible values:

* 0= Opens with '''default''' zoom magnification.
* 1= Opens magnified to '''fit''' the entire page '''within''' the '''window'''.
* 2= Opens magnified to '''fit''' the entire '''page''' '''width''' within the window.
* 3= Opens magnified to fit the entire width of its '''boundig''' '''box''' within the window (cuts out margins).
* 4= Opens with the '''zoom''' '''level''' specified in the Zoom property.

| <center>long</center>
| <center>0</center>

|-
| <code>Zoom</code>
| specifies the zoom level a PDF document is opened with. Only valid if "Magnification" is set to "4".
| <center>long</center>
| <center>100</center>

|-
| <code>PageLayout</code>
| Specifies the page layout to be used when the document is opened.

Possible values:

* 0= Display the pages according to the reader configuration.
* 1= Display one page at a time.
* 2= Display the pages in one column.
* 3= Display the pages in two columns odd pages on the right, to have the odd pages on the left the FirstPageOnLeft property should be used as well.

| <center>long</center>
| <center>0</center>

|-
| <code>FirstPageOnLeft</code>
| Used with the value 3 of the PageLayout property above, true if the first page (odd) should be on the left side of the screen.
| <center>boolean</center>
| <center>false</center>

|}

== User interface ==

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
! <center>Property Name</center>
! <center>Description</center>
! <center>Type</center>
! <center>Default value</center>

|-
| <code>ResizeWindowToInitialPage</code>
| Specifies that the PDF viewer window is opened '''full screen''' when the document is opened.
| <center>boolean</center>
| <center>false</center>

|-
| <code>CenterWindow</code>
| Specifies that the PDF viewer window is centered to the screen when the PDF document is opened.
| <center>boolean</center>
| <center>false</center>

|-
| <code>OpenInFullScreenMode</code>
| Specifies that the PDF viewer window is opened full screen, on top of all windows.
| <center>boolean</center>
| <center>false</center>

|-
| <code>DisplayPDFDocumentTitle</code>
| Specifies that the title of the document, if present in the document properties, is displayed in the PDF viewer window title bar.
| <center>boolean</center>
| <center>true</center>

|-
| <code>HideViewerMenubar</code>
| Specifies whether to hide the PDF viewer menubar when the document is active.
| <center>boolean</center>
| <center>false</center>

|-
| <code>HideViewerToolbar</code>
| Specifies whether to hide the PDF viewer toolbar when the document is active.
| <center>boolean</center>
| <center>false</center>

|-
| <code>HideViewerWindowControls</code>
| Specifies whether to hide the PDF viewer controls when the document is active.
| <center>boolean</center>
| <center>false</center>

|-
| <code>UseTransitionEffects</code>
| Specifies slide transitions are exported to PDF. This option is active only if storing '''Impress''' documents.
| <center>boolean</center>
| <center>true</center>

|-
| <code>OpenBookmarkLevels</code>
| Specifies how many bookmark levels should be opened in the reader application when the PDF gets opened.

Possible values:

* -1: all bookmark levels are opened
* 1 – 10: indicate a bookmark level (from 1 to 10)

| <center>long</center>
| <center>-1</center>

|}

== Links ==

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
! <center>Property Name</center>
! <center>Description</center>
! <center>Type</center>
! <center>Default value</center>

|-
| <code>ExportBookmarksToPDFDestination</code>
| Specifies that the bookmarks contained in the source OpenOffice.org file should be exported to the PDF file as Named Destination (see PDF 1.4 section 8.2.1).
| <center>boolean</center>
| <center>false</center>

|-
| <code>ConvertOOoTargetToPDFTarget</code>
| <nowiki>Specifies that the target documents with .od[tpgs] extension, will have that extension changed to .pdf when the link is exported to PDF. The source document remains untouched.</nowiki>
| <center>boolean</center>
| <center>false</center>

|-
| <code>ExportLinksRelativeFsys</code>
| Specifies that the file system related hyperlinks (file:// protocol) present in the document will be exported as relative to the source document location.
| <center>boolean</center>
| <center>false</center>

|-
| <code>PDFViewSelection</code>
| Specifies the way the exported PDF will be viewed (experienced) by the user.

Possible values:

* 0 = Specifies that the PDF will be exported with all the links external to the document treated as URI. This is the Default
* 1 = Specifies that the PDF will be exported in order to be viewed through a PDF reader application only. Valid only if not exporting to PDF/A-1 (e.g. SelectPdfVersion not set to 1).
* 2 = Specifies that the PDF will be exported in order to be viewed through an Internet browser, using the PDF plug-in provided with it. The bookmark of the URI will be rendered compatible with the target bookmark generated with OOo PDF Export feature (see ExportBookmarksToPDFDestination, below).

| <center>long</center>
| <center>0</center>

|}

== Security ==

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
! <center>Property Name</center>
! <center>Description</center>
! <center>Type</center>
! <center>Default value</center>

|-
| <code>EncryptFile</code>
| If true, selects to encrypt the PDF document with a password. The PDF file can be opened only when the user enters the correct password.
| <center>boolean</center>
| <center>false</center>

|-
| <code>DocumentOpenPassword</code>
| This is the password that allows the user to open the PDF file is "EncryptFile" is set to true.
| <center>string</center>
|

|-
| <code>RestrictPermissions</code>
| If true, selects to restrict some permissions. The permissions can be changed only when the user enters the correct password.
| <center>boolean</center>
| <center>false</center>

|-
| <code>PermissionPassword</code>
| This is the password that allows the user to access some permissions restricted if "RestrictPermissions" is set to true.
| <center>string</center>
|

|-
| <code>Printing</code>
| Specifies what printing is allowed.

Possible values:

* 0 = The document cannot be printed.
* 1 = The document can be printed at low resolution only.
* 2 = The document can be printed at maximum resolution.

| <center>long</center>
| <center>2</center>

|-
| <code>Changes</code>
| Specifies the change allowed to the document.

Possible values:

* 0 = The document cannot be changed.
* 1 = Inserting deleting and rotating pages is allowed.
* 2 = Filling of form field is allowed.
* 3 = Both filling of form field and commenting is allowed.
* 4 = All the changes of the previous selections are permitted, with the only exclusion of page extraction (copy).

| <center>long</center>
| <center>4</center>

|-
| <code>EnableCopyingOfContent</code>
| Specifies that the pages and the document content can be extracted to be used in other documents (copy and paste).
| <center>boolean</center>
| <center>true</center>

|-
| <code>EnableTextAccessForAccessibilityTools</code>
| Specifies that the document content can be extracted to be used in accessibility applications.
| <center>boolean</center>
| <center>true</center>

|}

= Filter data demo =

The following sample shows how to use the filer data to set some PDF export filter options.

We will create a new Writer document, insert some text in it and draw two shapes. Then we will show how to export only these two shapes, setting also some view preferences (the PDF will open in full screen mode).

<source lang="java">

// create a new Writer document using a helper
xComponent = Helper.createNewDoc(m_xContext, "swriter");

// access its XTextDocument interface
XTextDocument xTextDocument = (XTextDocument) UnoRuntime.queryInterface(
XTextDocument.class, xComponent);

// draw a group of shapes
// so that then we can select them and export ONLY them to PDF
XShapeGroup xShapes = drawShapeGroup(xTextDocument);

// XStorable to store the document
XStorable xStorable = (XStorable) UnoRuntime.queryInterface(
XStorable.class, xComponent);

// XStorable.storeToURL() expects an URL telling where to store the document
// and an array of PropertyValue indicating how to store it

// URL = use helper method to get the home directory
String sURL = Helper.getHomeDir(m_xContext) + "/PDF_EXPORT_FilterData_demo.pdf";

// Exporting to PDF consists of giving the proper
// filter name in the property "FilterName"
// With only this, the WHOLE document will be exported
// using the existing PDF export settings
// (the one used the last time, or the default if the first time)
PropertyValue[] aMediaDescriptor = new PropertyValue[2];
aMediaDescriptor[0] = new PropertyValue();
aMediaDescriptor[0].Name = "FilterName";
aMediaDescriptor[0].Value = "writer_pdf_Export";

// By adding the "FilterData" we can control what is exported and how
// For example, we will export ONLY the current selection

PropertyValue[] aFilterData = new PropertyValue[3];
aFilterData[0] = new PropertyValue();
aFilterData[0].Name = "Selection";
aFilterData[0].Value = select(xTextDocument, xShapes);
// there was really no need to retrieve the selection
// we could have used the XShapeGroup reference

aFilterData[1] = new PropertyValue();
aFilterData[1].Name = "DisplayPDFDocumentTitle";
aFilterData[1].Value = Boolean.FALSE;

aFilterData[2] = new PropertyValue();
aFilterData[2].Name = "OpenInFullScreenMode";
aFilterData[2].Value = Boolean.TRUE;

aMediaDescriptor[1] = new PropertyValue();
aMediaDescriptor[1].Name = "FilterData";
aMediaDescriptor[1].Value = aFilterData;

xStorable.storeToURL(sURL, aMediaDescriptor);

// open the PDF with your default PDF viewer
// to check how it worked!
Helper.executeSystemCommand(m_xContext, sURL);

</source>

To export the selection, there must be something currently selected in the document's ''view''; that is, if you "select" for example a text range by means of expanding a text cursor

<source lang="java">
XTextCursor xCursor = xTextDocument.getText().createTextCursor();

// The text cursor can travel through the text
// as a "collapsed" text range
// with identical start and end as a point in text,
// or it can expand while it moves to contain a target string.
// This is controlled with the XTextCursor methods
// having a boolean parameter, for example XTextCursor.gotoEnd(bExpand)
// If bExpand is true, the cursor expands while it travels

xCursor.gotoStart(false); // go to the start
xCursor.gotoEnd(true); // go to the end, expanding the cursor's text range

// now the cursor's text range covers all the document's text

//...

aFilterData[0] = new PropertyValue();
aFilterData[0].Name = "Selection";
aFilterData[0].Value = xCursor;
</source>

the PDF export filter will not recognize this as a selection: the text cursor is not collapsed (start and end are not the same), but nothing is selected in the document's view.

To select an object in the document's view is really simple: just get the current <idl>com.sun.star.frame.XController</idl> from the document <idl>com.sun.star.frame.XModel</idl>, query for the <code>XController</code>'s <idl>com.sun.star.view.XSelectionSupplier</idl>,and select the object (a cursor's text, a group of shapes, etc.):

<source lang="java">

private Object select(XInterface xInterface, Object aAny){
Object oSelection = null;
try {
XModel xModel = (XModel) UnoRuntime.queryInterface(
XModel.class, xInterface);
if (xModel != null){
XController xController = xModel.getCurrentController();
XSelectionSupplier xSelectionSupplier =
(XSelectionSupplier) UnoRuntime.queryInterface(
XSelectionSupplier.class, xController);
xSelectionSupplier.select(aAny);
// there is really no need to retrieve the selection
oSelection = xSelectionSupplier.getSelection();
}
} finally {
return oSelection;
}
}

</source>

= PDF Export Configuration =

Most of the PDF export filter properties seen in the tables above are stored in the OpenOffice.org configuration.

When the user clicks the toolbar icon to export the current document (command <code>".uno:ExportDirectToPDF"</code>), s/he will only see the "Export" dialog, not the "PDF Options" dialog. In this case, the filter will export reading the settings the user defined the last time in the PDF Options dialog (or the default settings if the dialog has never been used before).

If the user chooses the command in the "File" menu (<code>".uno:ExportToPDF"</code>), s/he will see two dialogs in succession: first the PDF Options dialog, where s/he chooses the export settings; then the "Export" dialog, where s/he enters a file name. The settings entered int the PDF Options dialog are made persistent.

The PDF export filter configuration is stored in the path <code>org.openoffice.Office/Common/PDF/Export</code>, its schema can be found in the office installation inside <code><nowiki><opt/openoffice.org2.4></nowiki>/share/registry/schema/org/openoffice/Office/Common.xcs</code>.

Not all properties passed to the PDF filter are stored in the registry (as it makes no sense, for example to make persistent the page range to be exported, or the passwords for protecting the document). The following is a list of the properties not stored in the OpenOffice.org registry:

# <code>DocumentOpenPassword</code>
# <code>EncryptFile</code>
# <code>PageRange</code>
# <code>PermissionPassword</code>
# <code>RestrictPermissions</code>
# <code>Selection</code>

The following property is present, but deprecated (that's why we didn't include in the tables above):

# <code>CompressMode</code> <nowiki>[deprecated]</nowiki>

In the next sections, we will show how to access this configuration, change it, and restore it to its default values. The reader should be familiar with OpenOffice.org configuration API, as explained in [[Documentation/DevGuide/Config/Configuration Management|Developer's Guide – Configuration Management]].

==Accessing the configuration==

To access the PDF export configuration, we must follow two steps, as explained in [[Documentation/DevGuide/Config/Configuration_Data_Sources|Developer's Guide – Configuration Management - Configuration Data Sources]]:

# connect to the OpenOffice.org registry that stores the user configuration data by creating an instance of a <idl>com.sun.star.configuration.ConfigurationProvider</idl> at the global service manager
# ask the <code>ConfigurationProvider</code> to create an access object for the nodepath <code>"/org.openoffice.Office/Common/PDF/Export"</code>, using <idlml>com.sun.star.lang.XMultiServiceFactory:createInstanceWithArguments</idlml>. Depending on if we want a read-only view of the configuration data, or we want it to be modifiable, we must pass to <code>createInstanceWithArguments()</code> the name of the service <idl>com.sun.star.configuration.ConfigurationAccess</idl>, for read-only access, or <idl>com.sun.star.configuration.ConfigurationUpdateAccess</idl>, for updatable access.

To create a '''read-only''' view on the PDF export filter configuration data in the user layer, the service <idl>com.sun.star.configuration.ConfigurationAccess</idl> is requested to the <idls>com.sun.star.configuration.ConfigurationProvider</idls>:

<source lang="java">

public static Object getPDFConfigAccess(XComponentContext xContext){

Object oPDFExportConfig = null;
try {
XMultiComponentFactory xMCF = xContext.getServiceManager();

// instantiate the ConfigurationProvider at the ServiceManager
Object oConfigProvider = xMCF.createInstanceWithContext(
"com.sun.star.configuration.ConfigurationProvider", xContext);

// query its XMultiServiceFactory:
// the ConfigurationProvider serves as a FACTORY for objects
// that provide access to a subset of the configuration.
XMultiServiceFactory oConfigProvMSF =
(XMultiServiceFactory) UnoRuntime.queryInterface(
XMultiServiceFactory.class, oConfigProvider);

// createInstanceWithArguments(sServiceSpecifier, aArguments)
// first parameter is the service specifier, in this case for read-only access:
String sServiceName = "com.sun.star.configuration.ConfigurationAccess";

// createInstanceWithArguments(sServiceSpecifier, aArguments)
// second parameter takes a sequence< any > for the arguments,
// mapped in Java to Object[]
Object[] args = new Object[1];

// The arguments passed to createInstanceWithArguments()
// in parameter aArguments specify the view of the configuration
// that should be created.
// Each element of the argument sequence should be a
// PropertyValue or a NamedValue.

// The "nodepath" argument contains the absolute path to
// the element of the configuration we want to create a view for.
NamedValue aNodepath= new NamedValue();
aNodepath.Name = "nodepath";
aNodepath.Value = "/org.openoffice.Office.Common/Filter/PDF/Export/";

args[0] = aNodepath;

// create the view
oPDFExportConfig = oConfigProvMSF.createInstanceWithArguments(
sServiceName, args);

} catch (Exception ex) {
ex.printStackTrace();
} finally {
return oPDFExportConfig;
}
}
</source>

The method for creating an '''updatable''' view is quite the same as the above, we only have to change the service specifier, so that <idl>com.sun.star.configuration.ConfigurationUpdateAccess</idl> is requested. In this case, there are other additional creation parameters available that control the caching behavior of the configuration management component, refer to [[Documentation/DevGuide/Config/Using_a_Data_Source|Developer's Guide - Configuration Mamagement - Using a Data Source]]. In the following sample, we use the defaults:

<source lang="java">
public static Object getPDFConfigUpdateAccess(XComponentContext xContext){

Object oPDFExportConfig = null;
try {
XMultiComponentFactory xMCF = xContext.getServiceManager();

// instantiate the ConfigurationProvider at the ServiceManager
Object oConfigProvider = xMCF.createInstanceWithContext(
"com.sun.star.configuration.ConfigurationProvider", xContext);

// query its XMultiServiceFactory:
// the ConfigurationProvider serves as a FACTORY for objects
// that provide access to a subset of the configuration.
XMultiServiceFactory oConfigProvMSF =
(XMultiServiceFactory) UnoRuntime.queryInterface(
XMultiServiceFactory.class, oConfigProvider);

// createInstanceWithArguments(sServiceSpecifier, aArguments)
// first parameter is the service specifier, in this case for UPDATE access:
String sServiceName = "com.sun.star.configuration.ConfigurationUpdateAccess";

// createInstanceWithArguments(sServiceSpecifier, aArguments)
// second parameter takes a sequence< any > for the arguments,
// mapped in Java to Object[]
Object[] args = new Object[1];

// The "nodepath" argument contains the absolute path to
// the element of the configuration we want to create a view for.
NamedValue aNodepath= new NamedValue();
aNodepath.Name = "nodepath";
aNodepath.Value = "/org.openoffice.Office.Common/Filter/PDF/Export/";

args[0] = aNodepath;

// create the view
oPDFExportConfig = oConfigProvMSF.createInstanceWithArguments(
sServiceName, args);

} catch (Exception ex) {
ex.printStackTrace();
} finally {
return oPDFExportConfig;
}
}
</source>

Both methods return in the Java sample a <code>java.lang.Object</code> (use <idl>com.sun.star.uno.XInterface</idl> in C++, and <code>Object</code> in OpenOffice.org Basic), as the view implements different interfaces you must query according to your needs.

==Read-only access==

The read-only view of the PDF export filter configuration we accessed with our method, supports the following services:

# <idl>com.sun.star.configuration.ConfigurationAccess</idl>
# <idl>com.sun.star.configuration.AccessRootElement</idl>
# <idl>com.sun.star.configuration.GroupAccess</idl>
# <idl>com.sun.star.configuration.HierarchyAccess</idl>
# <idl>com.sun.star.configuration.HierarchyElement</idl>
# <idl>com.sun.star.configuration.PropertyHierarchy</idl>

To access the PDF export filter properties we will query <idl>com.sun.star.beans.XPropertySet</idl>, and use its methods <idlm>com.sun.star.beans.XPropertySet:getPropertyValue</idlm> and <idlm>com.sun.star.beans.XPropertySet:getPropertySetInfo</idlm>. Notice that any attempt to invoke <idlm>com.sun.star.beans.XPropertySet:setPropertyValue</idlm> will throw an exception, as this is a read-only view.

<source lang="java">
public void run(){

Object oConfig = getPDFConfigAccess(m_xContext);

if (oConfig == null ) {
System.out.println("Impossible to access the PDF configuration");
return;
}

XPropertySet xPropertySet = (XPropertySet) UnoRuntime.queryInterface(
XPropertySet.class, oConfig);

XPropertySetInfo xPropertySetInfo = xPropertySet.getPropertySetInfo();

Property[] properties = xPropertySetInfo.getProperties();

System.out.println("\nProperties and values\n");

for (Property property : properties) {
String sValue = "";
try {
Object aValue = xPropertySet.getPropertyValue( property.Name );
sValue = String.valueOf( aValue );
} catch (Exception ex) {
ex.printStackTrace();
}
System.out.println(property.Name + " =\t" + sValue);
}
}
</source>

==Update access==

The '''updatable''' view of the PDF export filter configuration we accessed with our method, supports the following services:

# <idl>com.sun.star.configuration.ConfigurationAccess</idl>
# <idl>com.sun.star.configuration.ConfigurationUpdateAccess</idl>
# <idl>com.sun.star.configuration.AccessRootElement</idl>
# <idl>com.sun.star.configuration.UpdateRootElement</idl>
# <idl>com.sun.star.configuration.GroupAccess</idl>
# <idl>com.sun.star.configuration.GroupUpdate</idl>
# <idl>com.sun.star.configuration.HierarchyAccess</idl>
# <idl>com.sun.star.configuration.HierarchyElement</idl>
# <idl>com.sun.star.configuration.PropertyHierarchy</idl>

To change the configuration properties we proceed as above: query <idl>com.sun.star.beans.XPropertySet</idl>, but in this case we are able to invoke <idlm>com.sun.star.beans.XPropertySet:setPropertyValue</idlm>. Note that for better performance, you should try to use <idlml>com.sun.star.beans.XMultiPropertySet:setPropertyValues</idlml> instead.

<source lang="java">
public void run() {

Object oConfig = getPDFConfigUpdateAccess(m_xContext);

if (oConfig == null) {
System.out.println("Impossible to access the PDF configuration");
return;
}

XPropertySet xPropertySet = (XPropertySet) UnoRuntime.queryInterface(
XPropertySet.class, oConfig);

// for better performance use XMultiPropertySet
XMultiPropertySet xMultiPropertySet =
(XMultiPropertySet) UnoRuntime.queryInterface(
XMultiPropertySet.class, oConfig);

try {
// change some properties

/**
* The first property specifies that the resolution of each image
* must be reduced to the resolution specified by the second property
* The value is given in DPI.
*/
xPropertySet.setPropertyValue("ReduceImageResolution", Boolean.TRUE);
xPropertySet.setPropertyValue("MaxImageResolution", new Integer(600));

/**
* When exporting a document to PDF, the default is PDF 1.4
* Since OOo 2.4 the PDF/A-1a is also supported.
* PDF/A-1a is an ISO 19005-1:2005 International Standard.
*
* NOTE that some other options WILL NOT be available if this format
* is selected (UseTaggedPDF, ExportFormFileds, FormsType,
* all security options)
*/
xPropertySet.setPropertyValue("SelectPdfVersion", new Integer(1));

/**
* "Magnification" specifies the action to be performed
* when the PDF document is opened.
* A value of 4 opens with the zoom level specified in the
* "Zoom" property.
*/
xPropertySet.setPropertyValue("Magnification", new Integer(4));
xPropertySet.setPropertyValue("Zoom", new Integer(60));

// When using XMultiPropertySet:setPropertyValues(),
// properties must be alphabetically sorted!
String[] aProperties = { "CenterWindow", "DisplayPDFDocumentTitle",
"InitialView", "PageLayout" };
Object[] aValues = { Boolean.TRUE, Boolean.FALSE,
new Integer(2), new Integer(1)};

xMultiPropertySet.setPropertyValues(aProperties, aValues);

// commit the changes, otherwise they will be lost!
XChangesBatch xChangesBatch = (XChangesBatch) UnoRuntime.queryInterface(
XChangesBatch.class, oConfig);

xChangesBatch.commitChanges();

} catch (UnknownPropertyException ex) {
ex.printStackTrace();
} catch (PropertyVetoException ex) {
ex.printStackTrace();
} catch (IllegalArgumentException ex) {
ex.printStackTrace();
} catch (WrappedTargetException ex) {
ex.printStackTrace();
}
}
</source>

==Resetting the configuration==

Setting the configuration to its default values is very simple, just query the <idls>com.sun.star.configuration.ConfigurationUpdateAccess</idls>'s <idl>com.sun.star.beans.XMultiPropertyStates</idl>, and use its method <idlm>com.sun.star.beans.XMultiPropertyStates:setAllPropertiesToDefault</idlm>:

<source lang="java">
// get an updatable view
Object oConfig = ConfigUpdateAccess.getPDFConfigUpdateAccess(m_xContext);

if (oConfig == null) {
System.out.println("Impossible to access the PDF configuration");
return;
}

XMultiPropertyStates xMultiPropertyStates =
(XMultiPropertyStates) UnoRuntime.queryInterface(
XMultiPropertyStates.class, oConfig);
try {
// set all the properties to default values
xMultiPropertyStates.setAllPropertiesToDefault();

//you must commit the changes, if not they will be lost
XChangesBatch xChangesBatch = (XChangesBatch) UnoRuntime.queryInterface(
XChangesBatch.class, xMultiPropertyStates);

xChangesBatch.commitChanges();

} catch (WrappedTargetException ex) {
ex.printStackTrace();
}
</source>

=PDF Export Dialog=

==How to use it from Java==

<source lang="java">

import com.sun.star.beans.PropertyValue;
import com.sun.star.beans.XPropertyAccess;
import com.sun.star.io.IOException;
import com.sun.star.uno.XComponentContext;
import com.sun.star.comp.helper.Bootstrap;
import com.sun.star.document.XExporter;
import com.sun.star.frame.XComponentLoader;
import com.sun.star.frame.XStorable;
import com.sun.star.lang.XComponent;
import com.sun.star.lang.XMultiComponentFactory;
import com.sun.star.ui.dialogs.ExecutableDialogResults;
import com.sun.star.ui.dialogs.XExecutableDialog;
import com.sun.star.uno.AnyConverter;
import com.sun.star.uno.UnoRuntime;
import com.sun.star.util.CloseVetoException;
import com.sun.star.util.XCloseable;
import com.sun.star.util.XStringSubstitution;

public class PDFExportDialog {

private final XComponentContext m_xContext;

public PDFExportDialog(XComponentContext xContext){
m_xContext = xContext;
}

public static void main(String[] args) {
try {
// get the remote office component context
XComponentContext xContext = Bootstrap.bootstrap();

PDFExportDialog demo = new PDFExportDialog(xContext);
demo.run();

} catch (java.lang.Exception e){
e.printStackTrace();
}
finally {
System.exit( 0 );
}
}

public void run() {

XMultiComponentFactory xMCF = m_xContext.getServiceManager();

Object oPDFDialog = null;

try {
oPDFDialog = xMCF.createInstanceWithContext(
"com.sun.star.document.PDFDialog", m_xContext);
} catch (com.sun.star.uno.Exception ex) {
ex.printStackTrace();
}

// get all interface references
XExecutableDialog xExecutableDialog =
(XExecutableDialog) UnoRuntime.queryInterface(
XExecutableDialog.class, oPDFDialog);

XExporter xExporter = (XExporter) UnoRuntime.queryInterface(
XExporter.class, xExecutableDialog);

XPropertyAccess xPropertyAccess =
(XPropertyAccess) UnoRuntime.queryInterface(
XPropertyAccess.class, xExporter);

// check them all
if (xExecutableDialog == null ||
xExporter == null || xPropertyAccess == null) {
System.out.println("something went wrong with the PDFDialog!");
return;
}

XComponent xComponent = null;
try {
// change the following to test with different doc. types
// but remember to change the filter name below
xComponent = createNewDoc(m_xContext, "swriter");

// set the source document
xExporter.setSourceDocument(xComponent);

// set the title
xExecutableDialog.setTitle("Demo Export PDF Dialog OOo API");

// execute the dialog
int nResult = xExecutableDialog.execute();

if (nResult != ExecutableDialogResults.OK) {
System.out.println("you didn't press OK! so do nothing...");
return;
}

// get the options the user has choosen
PropertyValue[] aFilterData = null;

PropertyValue[] aPropertyValues = xPropertyAccess.getPropertyValues();
for (int i = 0; i < aPropertyValues.length; i++) {
PropertyValue propertyValue = aPropertyValues[i];
if (propertyValue.Name.equals("FilterData")) {
try {
aFilterData = (PropertyValue[]) AnyConverter.toObject(
PropertyValue[].class, propertyValue.Value);

} catch (com.sun.star.lang.IllegalArgumentException ex) {
ex.printStackTrace();
}
break;
}
}

if (aFilterData != null) {
// print the properties and their values
printPropertyValues(aFilterData);

// finally export!
// location where to export the doc.
String sURL = getHomeDir(m_xContext) + "/PDF_EXPORT_DIALOG_demo.pdf";
// choose the proper filter
String sFilter = "writer_pdf_Export";

boolean bExport = doExport(xComponent, sURL, sFilter, aFilterData);

System.out.println( (bExport) ? "\nExported!" :
"\nCouldn't export the document!" );
}

} catch (java.lang.Exception ex) {
ex.printStackTrace();
} finally {
if (xComponent != null) {
try {
XCloseable xCloseable = (XCloseable) UnoRuntime.queryInterface(
XCloseable.class, xComponent);
xCloseable.close(true);
} catch (CloseVetoException ex) {
ex.printStackTrace();
}
}
}
}

private boolean doExport(
XComponent xComponent,
String aURL,
String sFilterName,
PropertyValue[] aFilterData)
{
XStorable xStorable = (XStorable) UnoRuntime.queryInterface(
XStorable.class, xComponent);
if (xStorable == null) {
return false;
} else {
try {
PropertyValue[] aMediaDescriptor = new PropertyValue[2];

aMediaDescriptor[0] = new PropertyValue();
aMediaDescriptor[0].Name = "FilterName";
aMediaDescriptor[0].Value = sFilterName;

aMediaDescriptor[1] = new PropertyValue();
aMediaDescriptor[1].Name = "FilterData";
aMediaDescriptor[1].Value = aFilterData;

xStorable.storeToURL(aURL, aMediaDescriptor);
return true;

} catch (IOException ex) {
ex.printStackTrace();
}
}
return false;
}

public static void printPropertyValues(PropertyValue[] aPropertyValues)
{
System.out.println("\nProperties and values\n");

for (PropertyValue property : aPropertyValues) {
String sValue = "";
try {
sValue = String.valueOf(property.Value);
} catch (Exception ex) {
ex.printStackTrace();
}
System.out.println(property.Name + " = " + sValue);
}
}

//*************************************************************************

public static XComponent loadComponent(
XComponentContext xContext,
String sURL,
PropertyValue[] aMediaDescriptor)
{
XComponent xComp = null;
try {
XComponentLoader xComponentLoader = (XComponentLoader) UnoRuntime.queryInterface(
XComponentLoader.class,
xContext.getServiceManager().createInstanceWithContext(
"com.sun.star.frame.Desktop", xContext));
xComp = xComponentLoader.loadComponentFromURL(
sURL, "_default", 0, aMediaDescriptor);
} catch (Exception ex) {
ex.printStackTrace();
}
return xComp;
}

public static XComponent createNewDoc(
XComponentContext xContext,
String sDocType,
PropertyValue[] aMediaDescriptor)
{
XComponent xComp = null;
try {
xComp = loadComponent(xContext, "private:factory/" +
sDocType, aMediaDescriptor);
} catch (Exception ex) {
ex.printStackTrace();
}
return xComp;
}

public static XComponent createNewDoc(
XComponentContext xContext,
String sDocType)
{
XComponent xComp = null;
try {
xComp = createNewDoc(xContext, sDocType, new PropertyValue[0]);
} catch (Exception ex) {
ex.printStackTrace();
}
return xComp;
}

public static XComponent createNewHiddenDoc(
XComponentContext xContext,
String sDocType)
{
XComponent xComp = null;
try {
PropertyValue[] aMediaDescriptor = new PropertyValue[1];
aMediaDescriptor[0] = new PropertyValue();
aMediaDescriptor[0].Name = "Hidden";
aMediaDescriptor[0].Value = Boolean.TRUE;

xComp = createNewDoc(xContext, sDocType, aMediaDescriptor);

} catch (Exception ex) {
ex.printStackTrace();
}
return xComp;
}

//************************************************************************
//*************************************************************************

public static String getHomeDir(XComponentContext xContext) {
return getPathSubstitution(xContext, "$(home)");
}

public static String getWorkDir(XComponentContext xContext) {
return getPathSubstitution(xContext, "$(work)");
}

public static String getUserDir(XComponentContext xContext) {
return getPathSubstitution(xContext, "$(user)");
}

/**
*
* com.sun.star.util.PathSubstitution
*
* $(inst) Installation path of the Office.
* $(prog) Program path of the Office.
* $(user) The user installation directory.
* $(work) The work directory of the user.
* Under Windows this would be the "MyDocuments" subdirectory.
* Under Unix this would be the home-directory
* $(home) The home directory of the user.
* Under Unix this would be the home- directory.
* Under Windows this would be the "Documents and Settings\ " subdirectory.
* $(temp) The current temporary directory.
* $(path) The value of PATH environment variable.
* $(lang) The country code used by the Office, like
* 01=english,
* 49=german.
* $(langid) The language code used by the Office, like
* 0x0009=english,
* 0x0409=english us.
* $(vlang) The language used by the Office as a string. Like
* "german" for a german Office.
*
*/
public static String getPathSubstitution(
XComponentContext xContext, String aVariable)
{
String variableSubst = null;
try {
XStringSubstitution xStringSubstitution = getPathSubstitution(xContext);
variableSubst = xStringSubstitution.getSubstituteVariableValue(aVariable);

} catch (com.sun.star.container.NoSuchElementException e) {
e.printStackTrace();
} catch (com.sun.star.uno.Exception ex) {
ex.printStackTrace();
} finally {
return variableSubst;
}
}

public static String getPathSubstitution(
XComponentContext xContext, String aText, boolean bSubstRequired)
{
String variableSubst = null;
try {
XStringSubstitution xStringSubstitution = getPathSubstitution(xContext);
variableSubst = xStringSubstitution.substituteVariables(
aText, bSubstRequired);

} catch (com.sun.star.container.NoSuchElementException e) {
e.printStackTrace();
} catch (Exception ex) {
ex.printStackTrace();
} finally {
return variableSubst;
}
}

public static XStringSubstitution getPathSubstitution(
XComponentContext xContext)
{
XStringSubstitution xPathSubstitution = null;
XMultiComponentFactory xMCF = xContext.getServiceManager();
try {
xPathSubstitution = (XStringSubstitution) UnoRuntime.queryInterface(
XStringSubstitution.class,
xMCF.createInstanceWithContext(
"com.sun.star.util.PathSubstitution", xContext));
} catch (com.sun.star.uno.Exception ex) {
ex.printStackTrace();
} finally {
return xPathSubstitution;
}
}

}

</source>

==How to use it from C++==

ToDo

==How to use it from OOo Basic==

ToDo

{{PDL1}}
[[Category:API]]
[[Category:Tutorial]]
[[Category:Development]]

Documentation/DevGuide/OfficeDev/Filter

2010-02-26T06:22:50Z

Newacct:

{{Documentation/DevGuide/OfficeDevTOC
|OfficeDev2b=block
|OfficeDevInteg=block
|OfficeDevDocFilter=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/OfficeDev/Filtering Process
|NextPage=Documentation/DevGuide/OfficeDev/Configuring a Filter in OpenOffice.org
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/OfficeDev/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Filters}}

As described in the previous chapter, filters are objects that can be used to import or export content into or from {{PRODUCTNAME}} documents. The API defines the two services <idl>com.sun.star.document.ImportFilter</idl> and <idl>com.sun.star.document.ExportFilter</idl>. A filter implementation can support one or both of them. If a particular filter that only supports import is used, the imported document is modified by the user and then the user presses the "Save" button, a "Save As" operation will be carried out instead as {{PRODUCTNAME}} must assume that the filter component is "import only" and so storing must be done in a different format. It doesn't help to have a different export filter for the same content. If a direct "Save" operation should be possible, both filter services must be supported at the same filter object.

A filter is created from the factory service <idl>com.sun.star.document.FilterFactory</idl>. This service also provides a low-level access to the configuration that knows all registered filters of {{PRODUCTNAME}} and their properties, supports search and query functionality, and creates and initializes filter components. As an example, if the type name of a content is known, a query at the FilterFactory can be used to retrieve one or more internal filter names of possible filters and after chosing one of them the filter can be created using this name.

{{Documentation/Note|Many existing filters are legacy filters. The component loader or <code>XStorable</code> implementation does not use the <code>FilterFactory</code> to create them, but triggers filtering by internal C++ calls. So asking the FilterFactory to create such filter is not possible.}}

Filters can be initialized if they implement the interface <idl>com.sun.star.lang.XInitialization</idl>. The method <code>initialize()</code> is used by the filter factory service directly after creation of the filter object, before the filter is returned to the code that requested the filter. It passes the configuration data of the filter and all parameters and options that have been specified by the creation request to the factory. These properties usually originate from the "FilterOptions" property of the MediaDescriptor and have been put there either by the code requesting the loading or storing or by user input in a filter options dialog. How such filter dialog can be implemented is explained in the chapter about [[Documentation/DevGuide/OfficeDev/Filter_Options|filter options]].

The parameter list of <code>initialize()</code> uses the following protocol:

* The first item in the list is a sequence of <idl>com.sun.star.beans.PropertyValue</idl> structs, that describe the configuration properties of the filter.
* All other items are directly copied from the parameter Arguments of the factory interface method <idlml>com.sun.star.lang.XMultiServiceFactory:createInstanceWithArguments</idlml>().

{{Documentation/Caution|The interface provides functionality for reading and writing of this name. It is not allowed to change an internal filter name during runtime of {{PRODUCTNAME}}, because all filter names must be unique and it is not possible for a filter instance to alter its name. Calls to <idlml>com.sun.star.container.XNamed:setName</idlml>() should be ignored or forwarded to the <tt>FilterFactory</tt> service, which knows all unique names and can solve ambiguities!}}

The fact that a filter gets its own name passed as an argument can be used to use one filter implementation to act as several filters in the configuration. This is shown in the following code snippet of the implementation of a filter initialization:

<source lang="java">
private String m_sInternalName;
public void initialize( Object[] lArguments )
throws com.sun.star.uno.Exception
{
// no arguments - no initialization
if (lArguments.length<1)
return;
// Arguments[0] = own configuration data
com.sun.star.beans.PropertyValue[] lConfig =
(com.sun.star.beans.PropertyValue[])lArguments[0];

// Arguments[1..n] = optional arguments of create request
for (int n=1; n<lArguments.length; ++n)
{
...
}

// analyze own configuration data for our own internal
// filter name! Important for generic filter services,
// which are registered more then once. They can use this
// information to find out, which specialization of it
// is required.
for (int i=0; i<lConfig.length; ++i)
{
if (lConfig[i].Name.equals("Name"))
{
m_sInternalName =
AnyConverter.toString(lConfig[i].Value);

// Tip: A generic filter implementation can use this internal
// name at runtime, to detect which specialization of it is required.
if (m_sInternalName=="filter_format_1")
m_eHandle = E_FORMAT_1;
else
if (m_sInternalName=="filter_format_2")
...
}
}
}
</source>

In one single workflow filters can act as an import or an export filter. If content is loaded, the creator of the filter will use the <idl>com.sun.star.document.XImporter</idl> interface and its method <code>setTargetDocument()</code> to bind the filter to the document it should import into. If content is stored, the interface <idl>com.sun.star.document.XExporter</idl> and its method <code>setSourceDocument()</code> will bind the filter to the document it shall get data from. The filtering process is done by the same method in both cases: it's the <code>filter()</code> method of the <idl>com.sun.star.document.XFilter</idl> interface that both kinds of filters must support. Here the <code>MediaDescriptor</code> is passed to the filter.

{{Documentation/Tip|In an object that implements both import and export it is necessary to decide whether importing or exporting is asked for when the <tt>filter()</tt> method is called. The differentiator is whether setTargetDocument or setSourceDocument has been called before (see sample code below). The user of a filter is responsible to make this call in a valid order.}}

This example code shows how the required filter operation can be tracked inside the filter implementation easily:


<source lang="java">
private boolean m_bImport;

// used to tell us: "you will be used for import"
public void setTargetDocument(
com.sun.star.lang.XComponent xDocument )
throws com.sun.star.lang.IllegalArgumentException
{
m_bImport = true;
}

// used to tell us: "you will be used for export"
public void setSourceDocument(
com.sun.star.lang.XComponent xDocument )
throws com.sun.star.lang.IllegalArgumentException
{
m_bImport = false;
}

// detect required type of filter operation
public boolean filter(
com.sun.star.beans.PropertyValue[] lDescriptor )
{
boolean bState;
if (m_bImport)
bState = impl_import( lDescriptor );
else
bState = impl_export( lDescriptor );
return bState;
}
</source>

{{PDL1}}

[[Category:Documentation/Developer's Guide/Office Development]]

PyUNO samples

2010-02-25T09:24:50Z

Newacct:

{{Documentation/Candidate}}
OpenOffice.org comes with a set of scripts that work as a sample on how to programmatically generate certain tasks using PyUNO.

=== Hello World.py ===
This script print a Hello World in an Writer document. This uses the [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText] interface, the actual content is on the String value of the [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XTextRange.html XTextRange].

First step we define the HelloWorldPython() class, then we call the XSCRIPTCONTEXT which will let us work within a sub-environment from UNO. Notice we didn't import uno and we don't need to connect to OOo through the socket. Also we have the uno environment by calling getDocument().

Then we call the XText interface to call on the END and STRING methods to write up the "Hello World (in Python)".
<source lang=python>
# HelloWorld python script for the scripting framework

def HelloWorldPython( ):
"""Prints the string 'Hello World(in Python)' into the current document"""
#get the doc from the scripting context which is made available to all scripts
model = XSCRIPTCONTEXT.getDocument()
#get the XText interface
text = model.Text
#create an XTextRange at the end of the document
tRange = text.End
#and set the string
tRange.String = "Hello World (in Python)"
return None
</source>

=== Capitalize.py ===
This script will show how to modify existing content in a document. More specifically manipulate the format values from the text. We use common python string methods like '''isupper, upper, len and lower'''. And we use XSCRIPTCONTEXT (Learn about the [http://api.openoffice.org/docs/DevelopersGuide/ScriptingFramework/ScriptingFramework.xhtml XSCRIPTCONTEXT]) for the positioning of the text ([http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText] and [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XTextRange.html XTextRange] ), the control of the cursor ([http://api.openoffice.org/docs/common/ref/com/sun/star/text/XWordCursor.html xWordCursor]).

<source lang=python>
# helper function
def getNewString( theString ) :
if not theString or len(theString) ==0 :
return ""
# should we tokenize on "."?
if theString[0].isupper() and len(theString)>=2 and theString[1].isupper() :
# first two chars are UC => first UC, rest LC
newString=theString.capitalize();
elif theString[0].isupper():
# first char UC => all to LC
newString=theString.lower()
else: # all to UC.
newString=theString.upper()
return newString;

def capitalisePython( ):
"""Change the case of a selection, or current word from upper case, to first char upper case, to all lower case to upper case..."""

# The context variable is of type XScriptContext and is available to
# all BeanShell scripts executed by the Script Framework
xModel = XSCRIPTCONTEXT.getDocument()

#the writer controller impl supports the css.view.XSelectionSupplier interface
xSelectionSupplier = xModel.getCurrentController()

#see section 7.5.1 of developers' guide
xIndexAccess = xSelectionSupplier.getSelection()
count = xIndexAccess.getCount();
for i in range(count) :
xTextRange = xIndexAccess.getByIndex(i);
#print "string: " + xTextRange.getString();
theString = xTextRange.getString();
if len(theString)==0 :
# sadly we can have a selection where nothing is selected
# in this case we get the XWordCursor and make a selection!
xText = xTextRange.getText();
xWordCursor = xText.createTextCursorByRange(xTextRange);
if not xWordCursor.isStartOfWord():
xWordCursor.gotoStartOfWord(False);
xWordCursor.gotoNextWord(True);
theString = xWordCursor.getString();
newString = getNewString(theString);
if newString :
xWordCursor.setString(newString);
xSelectionSupplier.select(xWordCursor);
else :
newString = getNewString( theString );
if newString:
xTextRange.setString(newString);
xSelectionSupplier.select(xTextRange);

# lists the scripts, that shall be visible inside OOo. Can be omitted, if
# all functions shall be visible, however here getNewString shall be suppressed
g_exportedScripts = capitalisePython,
</source>

=== TableSample.py ===

On this script we abandon the XSCRIPTCONTEXT and use the UNO module. We also use nested modules from Text, AWT, and LANG. Since we using the UNO module we have to import what we need straight from the com.sun.star path.

The first step is to get the functions for generating the document, and the other for manipulating the content. The document and content is under the '''createTable()''', while '''insertTextIntoCell()''' will handle the positioning within the table.

<source lang=python>
import uno

# a UNO struct later needed to create a document
from com.sun.star.text.ControlCharacter import PARAGRAPH_BREAK
from com.sun.star.text.TextContentAnchorType import AS_CHARACTER
from com.sun.star.awt import Size

from com.sun.star.lang import XMain

def insertTextIntoCell( table, cellName, text, color ):
tableText = table.getCellByName( cellName )
cursor = tableText.createTextCursor()
cursor.setPropertyValue( "CharColor", color )
tableText.setString( text )

def createTable():
"""creates a new writer document and inserts a table with some data (also known as the SWriter sample)"""
ctx = uno.getComponentContext()
smgr = ctx.ServiceManager
desktop = smgr.createInstanceWithContext( "com.sun.star.frame.Desktop",ctx)

# open a writer document
doc = desktop.loadComponentFromURL( "private:factory/swriter","_blank", 0, () )

text = doc.Text
cursor = text.createTextCursor()
text.insertString( cursor, "The first line in the newly created text document.\n", 0 )
text.insertString( cursor, "Now we are in the second line\n" , 0 )

# create a text table
table = doc.createInstance( "com.sun.star.text.TextTable" )

# with 4 rows and 4 columns
table.initialize( 4,4)

text.insertTextContent( cursor, table, 0 )
rows = table.Rows

table.setPropertyValue( "BackTransparent", uno.Bool(0) )
table.setPropertyValue( "BackColor", 13421823 )
row = rows.getByIndex(0)
row.setPropertyValue( "BackTransparent", uno.Bool(0) )
row.setPropertyValue( "BackColor", 6710932 )

textColor = 16777215

insertTextIntoCell( table, "A1", "FirstColumn", textColor )
insertTextIntoCell( table, "B1", "SecondColumn", textColor )
insertTextIntoCell( table, "C1", "ThirdColumn", textColor )
insertTextIntoCell( table, "D1", "SUM", textColor )

values = ( (22.5,21.5,121.5),
(5615.3,615.3,-615.3),
(-2315.7,315.7,415.7) )
table.getCellByName("A2").setValue(22.5)
table.getCellByName("B2").setValue(5615.3)
table.getCellByName("C2").setValue(-2315.7)
table.getCellByName("D2").setFormula("sum <A2:C2>")

table.getCellByName("A3").setValue(21.5)
table.getCellByName("B3").setValue(615.3)
table.getCellByName("C3").setValue(-315.7)
table.getCellByName("D3").setFormula("sum <A3:C3>")

table.getCellByName("A4").setValue(121.5)
table.getCellByName("B4").setValue(-615.3)
table.getCellByName("C4").setValue(415.7)
table.getCellByName("D4").setFormula("sum <A4:C4>")

cursor.setPropertyValue( "CharColor", 255 )
cursor.setPropertyValue( "CharShadowed", uno.Bool(1) )

text.insertControlCharacter( cursor, PARAGRAPH_BREAK, 0 )
text.insertString( cursor, " This is a colored Text - blue with shadow\n" , 0 )
text.insertControlCharacter( cursor, PARAGRAPH_BREAK, 0 )

textFrame = doc.createInstance( "com.sun.star.text.TextFrame" )
textFrame.setSize( Size(15000,400))
textFrame.setPropertyValue( "AnchorType" , AS_CHARACTER )

text.insertTextContent( cursor, textFrame, 0 )

textInTextFrame = textFrame.getText()
cursorInTextFrame = textInTextFrame.createTextCursor()
textInTextFrame.insertString( cursorInTextFrame, "The first line in the newly created text frame.", 0 )
textInTextFrame.insertString( cursorInTextFrame, "\nWith this second line the height of the rame raises.",0)
text.insertControlCharacter( cursor, PARAGRAPH_BREAK, 0 )

cursor.setPropertyValue( "CharColor", 65536 )
cursor.setPropertyValue( "CharShadowed", uno.Bool(0) )

text.insertString( cursor, " That's all for now !!" , 0 )

g_exportedScripts = createTable,
</source>

First step to understand is that the UNO module will give us the IDL binding from the API. We will then import specific things from the UNO module. For that we need to specify the path from com.sun.star and import the interfaces and services.

The nested modules [http://api.openoffice.org/docs/common/ref/com/sun/star/text/module-ix.html text] we had: [http://api.openoffice.org/docs/common/ref/com/sun/star/text/ControlCharacter.html ControlCharacter], [http://api.openoffice.org/docs/common/ref/com/sun/star/text/TextContentAnchorType.html TextContentAnchorType] and import [http://api.openoffice.org/docs/common/ref/com/sun/star/text/ControlCharacter.html#PARAGRAPH_BREAK PARAGRAPH_BREAK], [http://api.openoffice.org/docs/common/ref/com/sun/star/text/TextContentAnchorType.html#AS_CHARACTER AS_CHARACTER].

From [http://api.openoffice.org/docs/common/ref/com/sun/star/awt/module-ix.html awt] which is a user interface toolkit had: [http://api.openoffice.org/docs/common/ref/com/sun/star/awt/Size.html Size]

Finally [http://api.openoffice.org/docs/common/ref/com/sun/star/lang/module-ix.html lang] nested module which is about , we import [http://api.openoffice.org/docs/common/ref/com/sun/star/lang/XMain.html XMain].

<source lang=python>
import uno

# a UNO struct later needed to create a document
from com.sun.star.text.ControlCharacter import PARAGRAPH_BREAK
from com.sun.star.text.TextContentAnchorType import AS_CHARACTER
from com.sun.star.awt import Size

from com.sun.star.lang import XMain
</source>

==== createTable() ====

We can divide this class into the process of:
* creating a new window
* creating a writer document
* inserting text (previously seen on the Hello World Script).
* Creating a table within the writer document
* manipulate the format and finally the content
* Then we insert a frame with text in it
* insert a string

This let us analyze in more detail the interfaces and methods from the cursor, table, text, textFrame and textInTextFrame. All this documentation can be found on the IDL reference. Following this script will allow us to use the IDL to our benefit and explore other nested modules for different purpose.

The following values goes extract from the following:

* doc = desktop.'''loadComponentFromURL( "private:factory/swriter","_blank", 0, () )'''
* text = doc.Text
* cursor = text.'''createTextCursor()'''
* table = doc.'''createInstance( "com.sun.star.text.TextTable" )'''

The '''loadcomponentFromURL()''' creates and load the Writer document by generating the variable. Text is a variable that will get the document object with the module of Text. The function of '''createTextCursor()''' according with the IDL ''a new instance of a TextCursor service which can be used to travel in the given text context''.
<source lang=python>
"""creates a new writer document and inserts a table with some data (also known as the SWriter sample)"""
ctx = uno.getComponentContext()
smgr = ctx.ServiceManager
desktop = smgr.createInstanceWithContext( "com.sun.star.frame.Desktop",ctx)

# open a writer document
doc = desktop.loadComponentFromURL( "private:factory/swriter","_blank", 0, () )

text = doc.Text
cursor = text.createTextCursor()
text.insertString( cursor, "The first line in the newly created text document.\n", 0 )
text.insertString( cursor, "Now we are in the second line\n" , 0 )</source>
The next instance is the creation of the table instance within the table variable. We use the function of '''createTextCursor()''', the path to the module is '''com.sun.star.text.TextTable'''.
<source lang=python>
# create a text table
table = doc.createInstance( "com.sun.star.text.TextTable" )
</source>
We create our table by using the method '''initialize''' on the line 35 of the code '''table.initialize( 4,4)'''. Now we will deal with the properties of the table as well as the methods and objects from the table like rows, cursor and values. First step after initialize the table, we use the function '''insertTextContent( cursor, table, 0 )''', if you think that this will put a cursor in the table, then you are RIGHT. TextContent is basically an object which can be anchored in a text, like instances of TextFrame or TextFields. In our case we will deal with Cells rather than Frames or Fields.
<source lang=python>

# with 4 rows and 4 columns
table.initialize( 4,4)

text.insertTextContent( cursor, table, 0 )
rows = table.Rows</source>
The next point is we will focus on the '''styles''' of the table and have methods such as '''setPropertyValue''' which could might as well be setStyleValue being implemented to the text, for example '''setPropertyValue( "BackTransparent", uno.Bool(0) )''' or '''setPropertyValue( "BackColor", 6710932 )'''.
<source lang=python>
table.setPropertyValue( "BackTransparent", uno.Bool(0) )
table.setPropertyValue( "BackColor", 13421823 )
row = rows.getByIndex(0)
row.setPropertyValue( "BackTransparent", uno.Bool(0) )
row.setPropertyValue( "BackColor", 6710932 )</source>
The next step is to get the header of the table which will use the other class and will insert the values that we need, we get '''insertTextIntoCell( table, "A1", "FirstColumn", textColor )''' put color and content into the specific cells from the table object. The syntax is rather straight forward by stating object, cell position, text content and finally text color value which in this case is a variable of the hex color 16777215.
<source lang=python>
textColor = 16777215

insertTextIntoCell( table, "A1", "FirstColumn", textColor )
insertTextIntoCell( table, "B1", "SecondColumn", textColor )
insertTextIntoCell( table, "C1", "ThirdColumn", textColor )
insertTextIntoCell( table, "D1", "SUM", textColor )</source>
Now we will insert the content of our table including the numerical value and '''formula'''. We use an array of values and then generate a series of inserting the '''values()''' within the the '''getCellByName()''', '''setValue()''' and '''setFormula'''.
<source lang=python>
values = ( (22.5,21.5,121.5),
(5615.3,615.3,-615.3),
(-2315.7,315.7,415.7) )
table.getCellByName("A2").setValue(22.5)
table.getCellByName("B2").setValue(5615.3)
table.getCellByName("C2").setValue(-2315.7)
table.getCellByName("D2").setFormula("sum <A2:C2>")</source>

==== insertTextIntoCell() ====
This is a sub-process class which brings the services and methods for the table manipulation. The function uses the method getCellbyName, createTextCursor and createPropertyValue.

This insertTextIntoCell() function will bring a structure to format the header of the table.

[[Category:Python]]
[[Category:Uno]]
[[Category:Tutorial]]

Documentation/DevGuide/WritingUNO/Class Definition with Helper Class

2010-02-07T06:02:32Z

Newacct: /* XServiceInfo */

{{Documentation/DevGuide/WritingUNOTOC
|WritingUNO2c=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/WritingUNO/Simple Component in Java
|NextPage=Documentation/DevGuide/WritingUNO/Implementing Your Own Interfaces
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/WritingUNO/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Class Definition with Helper Class}}
=== XInterface, XTypeProvider and XWeak ===

The {{PRODUCTNAME}} Java UNO environment contains Java helper classes that implement the majority of the core interfaces that are implemented by UNO components. There are two helper classes:

* The helper <code>com.sun.star.lib.uno.helper.WeakBase</code> is the minimal base class and implements <code>XInterface</code>, <code>XTypeProvider</code> and <code>Xweak</code>.
* The helper <code>com.sun.star.lib.uno.helper.ComponentBase</code> that extends <code>WeakBase</code> and implements <code>XComponent</code>.
The <idl>com.sun.star.lang.XServiceInfo</idl> is the only interface that should be implemented, but it is not part of the helpers.

Use the naming conventions described in section [[Documentation/DevGuide/WritingUNO/XServiceInfo|XServiceInfo]] for the service implementation. Following the rules, a service <code>org.openoffice.test.ImageShrink</code> should be implemented in <code>org.openoffice.''comp''.test.ImageShrink</code>.

A possible class definition that uses <code>WeakBase</code> could look like this: 
<source lang="java">
package org.openoffice.comp.test;

public class ImageShrink extends com.sun.star.lib.uno.helper.WeakBase
implements com.sun.star.lang.XServiceInfo,
org.openoffice.test.XImageShrinkFilter {

com.sun.star.uno.XComponentContext xComponentContext = null;

/** Creates a new instance of ImageShrink */
public ImageShrink(com.sun.star.uno.XComponentContext XComponentContext xContext) {
this.xComponentContext = xContext;
}
...

}
</source >
=== XServiceInfo ===

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

<source lang="java">
...

//XServiceInfo implementation

// hold the service name in a private static member variable of the class
protected static final String __serviceName = "org.openoffice.test.ImageShrink";

public String getImplementationName( ) {
return getClass().getName();
}

public boolean supportsService(String serviceName) {
return serviceName.equals( __serviceName);
}

public String[] getSupportedServiceNames( ) {
return new String[] { __serviceName };
}

...
</source >
An implementation of more than one service in one UNO object is more complex. It has to return all supported service names in <code>getSupportedServiceNames()</code>, furthermore it must check all supported service names in <code>supportsService()</code>. Note that several services packaged in one component file are not discussed here, but objects supporting more than one service. Refer to [[:Image:ComponentOverview2.png|A Component implementing three UNO objects]] for the implementation of srv3_4.

{{PDL1}}

[[Category:Documentation/Developer's Guide/Writing UNO Components]]

Counter Example

2010-02-06T09:48:07Z

Newacct:

This example given with the SDK contains two files : counter.cxx and countermain.cxx. These files show differencies with [[Constructing_Components#A_very_simple_Counter|Listing 3 and Listing 4]] previously tackled because they have to run with OpenOffice.org now. But they do the same work !

The generated counter, like ProfUnoLifeTime, is able to run even if OpenOffice isn't running.
MainCounter in the Figure below is the binary program file to run to test the example. There is no direct arrow between MainCounter and Counter.uno.so, indicating that they are independent of each other : if MainCounter want something from Counter.uno.so, it has to ask to cppuhelper (in other words to Openoffice).

== Compilation Chain ==

This little example uses a registered external module (counter.uno.so build from counter.cxx) and a main program (countermain.cxx) which uses it.
We shows with the figure below what tools are involved in the construction of the counter :

[[Image:MakefileCounterEx.png|center|thumb|800px|Counter Example : the Compilation Chain]]

The compilation chain for this example (see Figure above) is more complicated than [[Constructing_Components#Make_dependency_of_a_Component|previously]], because of the two cpp source files : counter.cxx and countermain.cxx. Please note we have to create a third file in this example : XCounter.idl.

== IDL File ==
The listing of this IDL file is now comprehensive by a reader who have studied [[IDL_Files_and_Cpp|IDL Files and Cpp]] section :

<source lang="idl">
//Listing 6 The IDL Counter File
// IDL
#include <com/sun/star/uno/XInterface.idl>

module foo
{
/**
* Interface to count things.
*/
interface XCountable : com::sun::star::uno::XInterface
{
long getCount();
void setCount( [in] long nCount );
long increment();
long decrement();
};

service Counter
{
// exported interface:
interface XCountable;
};
};
</source>
This IDL file describe the interface of counter.cxx which will become counter.uno.so (counter.uno.dll under Windows), a library file after compilation. But again you call one of the four method not directly but through cppuhelper. We give a schematic representation of this IDL file.

[[Image:ServiceCounter.png|center|thumb|600px|Counter Service and Interface]]

== The Counter Class ==
We give the listing of the counter class :

<source lang="cpp">
// Listing 7
// C++
//==================================================================================================
class MyCounterImpl
: public XCountable
, public XServiceInfo
{
// to obtain other services if needed
Reference< XMultiServiceFactory > m_xServiceManager;

sal_Int32 m_nRefCount;
sal_Int32 m_nCount;

public:
MyCounterImpl( const Reference< XMultiServiceFactory > & xServiceManager )
: m_xServiceManager( xServiceManager ), m_nRefCount( 0 )
{ printf( "< MyCounterImpl ctor called >\n" ); }
~MyCounterImpl()
{ printf( "< MyCounterImpl dtor called >\n" ); }

// XInterface implementation
virtual void SAL_CALL acquire() throw ()
{ ++m_nRefCount; }
virtual void SAL_CALL release() throw ()
{ if (! --m_nRefCount) delete this; }
virtual Any SAL_CALL queryInterface( const Type & rType ) throw (RuntimeException)
{ return cppu::queryInterface(rType,
static_cast< XInterface* >( static_cast< XServiceInfo* >( this ) ),
static_cast< XCountable* >( this ),
static_cast< XServiceInfo* >( this ) ); }

// XServiceInfo implementation
virtual OUString SAL_CALL getImplementationName( ) throw(RuntimeException);
virtual sal_Bool SAL_CALL supportsService( const OUString& ServiceName ) throw(RuntimeException);
virtual Sequence< OUString > SAL_CALL getSupportedServiceNames( ) throw(RuntimeException);
static Sequence< OUString > SAL_CALL getSupportedServiceNames_Static( );

// XCountable implementation
virtual sal_Int32 SAL_CALL getCount() throw (RuntimeException)
{ return m_nCount; }
virtual void SAL_CALL setCount( sal_Int32 nCount ) throw (RuntimeException)
{ m_nCount = nCount; }
virtual sal_Int32 SAL_CALL increment() throw (RuntimeException)
{ return (++m_nCount); }
virtual sal_Int32 SAL_CALL decrement() throw (RuntimeException)
{ return (--m_nCount); }
};

//*************************************************************************
OUString SAL_CALL MyCounterImpl::getImplementationName( )
throw(RuntimeException)
{
return OUString( RTL_CONSTASCII_USTRINGPARAM(IMPLNAME) );
}

//*************************************************************************
sal_Bool SAL_CALL MyCounterImpl::supportsService( const OUString& ServiceName )
throw(RuntimeException)
{
Sequence< OUString > aSNL = getSupportedServiceNames();
const OUString * pArray = aSNL.getArray();
for( sal_Int32 i = 0; i < aSNL.getLength(); i++ )
if( pArray[i] == ServiceName )
return sal_True;
return sal_False;
}

//*************************************************************************
Sequence<OUString> SAL_CALL MyCounterImpl::getSupportedServiceNames( )
throw(RuntimeException)
{
return getSupportedServiceNames_Static();
}

//*************************************************************************
Sequence<OUString> SAL_CALL MyCounterImpl::getSupportedServiceNames_Static( )
{
OUString aName( RTL_CONSTASCII_USTRINGPARAM(SERVICENAME) );
return Sequence< OUString >( &aName, 1 );
}

/**
* Function to create a new component instance; is needed by factory helper implementation.
* @param xMgr service manager to if the components needs other component instances
*/
Reference< XInterface > SAL_CALL MyCounterImpl_create(
const Reference< XMultiServiceFactory > & xMgr )
{
return Reference< XCountable >( new MyCounterImpl( xMgr ) );
}

//##################################################################################################
//#### EXPORTED ####################################################################################
//##################################################################################################
/**
* Gives the environment this component belongs to.
*/
extern "C" void SAL_CALL component_getImplementationEnvironment(const sal_Char ** ppEnvTypeName, uno_Environment ** ppEnv)
{
*ppEnvTypeName = CPPU_CURRENT_LANGUAGE_BINDING_NAME;
}
/**
* This function creates an implementation section in the registry and another subkey
*
* for each supported service.
* @param pServiceManager the service manager
* @param pRegistryKey the registry key
*/
extern "C" sal_Bool SAL_CALL component_writeInfo(void * pServiceManager, void * pRegistryKey)
{
sal_Bool result = sal_False;

if (pRegistryKey)
{
try
{
Reference< XRegistryKey > xNewKey(
reinterpret_cast< XRegistryKey * >( pRegistryKey )->createKey(
OUString( RTL_CONSTASCII_USTRINGPARAM("/" IMPLNAME "/UNO/SERVICES") ) ) );

const Sequence< OUString > & rSNL =
MyCounterImpl::getSupportedServiceNames_Static();
const OUString * pArray = rSNL.getConstArray();
for ( sal_Int32 nPos = rSNL.getLength(); nPos--; )
xNewKey->createKey( pArray[nPos] );

return sal_True;
}
catch (InvalidRegistryException &)
{
// we should not ignore exceptions
}
}
return result;
}
/**
* This function is called to get service factories for an implementation.
*
* @param pImplName name of implementation
* @param pServiceManager a service manager, need for component creation
* @param pRegistryKey the registry key for this component, need for persistent data
* @return a component factory
*/
extern "C" void * SAL_CALL component_getFactory(const sal_Char * pImplName, void * pServiceManager, void * pRegistryKey)
{
void * pRet = 0;

if (rtl_str_compare( pImplName, IMPLNAME ) == 0)
{
Reference< XSingleServiceFactory > xFactory( createSingleFactory(
reinterpret_cast< XMultiServiceFactory * >( pServiceManager ),
OUString( RTL_CONSTASCII_USTRINGPARAM(IMPLNAME) ),
MyCounterImpl_create,
MyCounterImpl::getSupportedServiceNames_Static() ) );

if (xFactory.is())
{
xFactory->acquire();
pRet = xFactory.get();
}
}

return pRet;
}
</source>
This is a lot of code compared with [[Constructing_Components#A_very_simple_Counter|Listing 3]]. This class will be compiled as a dynamic library and to be registered (see [[Constructing_Components#Making_the_Counter_registerable|Making the Counter registerable]]).

== The countermain program ==
<source lang="cpp">
// Listing 8
// C++ countermain.cxx
int SAL_CALL main(int argc, char **argv)
{
Reference< XSimpleRegistry > xReg = createSimpleRegistry();
OSL_ENSURE( xReg.is(), "### cannot get service instance of \"com.sun.star.regiystry.SimpleRegistry\"!" );

xReg->open(OUString::createFromAscii("counter.uno.rdb"), sal_False, sal_False);
OSL_ENSURE( xReg->isValid(), "### cannot open test registry \"counter.uno.rdb\"!" );

Reference< XComponentContext > xContext = bootstrap_InitialComponentContext(xReg);
OSL_ENSURE( xContext.is(), "### cannot creage intial component context!" );

Reference< XMultiComponentFactory > xMgr = xContext->getServiceManager();
OSL_ENSURE( xMgr.is(), "### cannot get initial service manager!" );

// register my counter component
Reference< XImplementationRegistration > xImplReg(
xMgr->createInstanceWithContext(OUString::createFromAscii("com.sun.star.registry.ImplementationRegistration"), xContext), UNO_QUERY);
OSL_ENSURE( xImplReg.is(), "### cannot get service instance of \"com.sun.star.registry.ImplementationRegistration\"!" );

if (xImplReg.is())
{
xImplReg->registerImplementation(
OUString::createFromAscii("com.sun.star.loader.SharedLibrary"), // loader for component
#ifdef UNX
#ifdef MACOSX
OUString::createFromAscii("counter.uno.dylib"), // component location
#else
OUString::createFromAscii("counter.uno.so"), // component location
#endif
#else
OUString::createFromAscii("counter.uno.dll"), // component location
#endif
Reference< XSimpleRegistry >() // registry omitted,
// defaulting to service manager registry used
);

// get a counter instance
Reference< XInterface > xx ;
xx = xMgr->createInstanceWithContext(OUString::createFromAscii("foo.Counter"), xContext);
Reference< XCountable > xCount( xx, UNO_QUERY );
OSL_ENSURE( xCount.is(), "### cannot get service instance of \"foo.Counter\"!" );

if (xCount.is())
{
xCount->setCount( 42 );
printf( "%d," , xCount->getCount() );
printf( "%d," , xCount->increment() );
printf( "%d\n" , xCount->decrement() );
}
}

Reference< XComponent >::query( xContext )->dispose();
return 0;
}
</source>

This is a lot of code compared with [[Constructing_Components#A_very_simple_Counter|Listing 4]]. One reason is because we have to register now the previous counter class : this is done in this program between lines 16 and 36.

{{Documentation/Tip|'''Please note''' this example doesn't require an OpenOffice running.}}

Return to [[Constructing_Components |Constructing Component]] or to "Using C++ with OOo SDK" [[Using_Cpp_with_the_OOo_SDK|main page]]

[[Category:MacOSX]]
[[Category:Cpp]]
[[Category:Uno]]

Documentation/DevGuide/ProUNO/Differences Between the Lifetime of C++ and Java Objects

2010-02-06T09:47:29Z

Newacct:

{{Documentation/DevGuide/ProUNOTOC
|ProUNO2b=block
|ProUNO2bLife=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/ProUNO/Weak Objects and References
|NextPage=Documentation/DevGuide/ProUNO/Object Identity
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/ProUNO/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Differences Between the Lifetime of C++ and Java Objects}}
{{Documentation/Note|Read [[Documentation/DevGuide/ProUNO/C++/C++ Language Binding|C++ Language Binding]] and [[Documentation/DevGuide/ProUNO/Java/Java Language Binding|Java Language Binding]] for information on language bindings, and [[Documentation/DevGuide/WritingUNO/C++/C++ Component|C++ Component]] and [[Documentation/DevGuide/WritingUNO/Storing the Service Manager for Further Use|Storing the Service Manager for Further Use]] about component implementation before beginning this section.}}

The implementation of the reference count specification is different in Java UNO and C++ UNO. In C++ UNO, every object maintains its own reference counter. When you implement a C++ UNO object, instantiate it, acquire it and afterwards release it, the destructor of the object is called immediately. The following example uses the standard helper class <code>::cppu::OWeakObject</code> and prints a message when the destructor is called. 
<source lang="cpp">
class MyOWeakObject : public ::cppu::OWeakObject
{
public:
MyOWeakObject() { printf( "constructed\n" ); }
~MyOWeakObject() { printf( "destroyed\n" ); }
};
</source>
The following method creates a new <code>MyOWeakObject</code>, acquires it and releases it for demonstration purposes. The call to release() immediately leads to the destruction of <code>MyOWeakObject</code>. If the <code>Reference<></code> template is used, you do not need to care about <code>acquire()</code> and <code>release()</code>.
<source lang="cpp">
void simple_object_creation_and_destruction()
{
// create the UNO object
com::sun::star::uno::XInterface * p = new MyOWeakObject();

// acquire it
p->acquire();

// release it
printf( "before release\n" );
p->release();
printf( "after release\n" );
}
</source>
This piece of code produces the following output:

constructed
before release
destroyed
after release

Java UNO objects behave differently, because they are finalized by the garbage collector at a time of its choosing. <idl>com.sun.star.uno.XInterface</idl> has no methods in the Java UNO language binding, therefore no methods need to be implemented, although MyUnoObject implements XInterface:

<source lang="java">
class MyUnoObject implements com.sun.star.uno.XInterface {

public MyUnoObject() {
}

void finalize() {
System.out.println("finalizer called");
}

static void main(String args[]) throws java.lang.InterruptedException {
com.sun.star.uno.XInterface a = new MyUnoObject();
a = null;

// ask the garbage collector politely
System.gc();
System.runFinalization();

System.out.println("leaving");

// It is java VM dependent, whether or not the finalizer was called
}
}
</source>
The output of this code depends on the Java VM implementation. The output "finalizer called" is not a usual result. Be aware of the side effects when UNO brings Java and C++ together.

When a UNO C++ object is mapped to Java, a Java proxy object is created that keeps a hard UNO reference to the C++ object. The UNO core takes care of this. The Java proxy only clears the reference when it enters the <code>finalize()</code> method, thus the destruction of the C++ object is delayed until the Java VM collects some garbage.

When a UNO Java object is mapped to C++, a C++ proxy object is created that keeps a hard UNO reference to the Java object. Internally, the Java UNO bridge keeps a Java reference to the original Java object. When the C++ proxy is no longer used, it is destroyed immediately. The Java UNO bridge is notified and immediately frees the Java reference to the original Java object. When the Java object is finalized is dependent on the garbage collector.

When a Java program is connected to a running {{PRODUCTNAME}}, the UNO objects in the office process are not destroyed until the garbage collector finalizes the Java proxies or until the interprocess connection is closed (see [[Documentation/DevGuide/ProUNO/UNO Interprocess Connections|UNO Interprocess Connections]]).

{{PDL1}}

[[Category:Documentation/Developer's Guide/Professional UNO]]

Documentation/DevGuide/Text/Inserting Tables

2010-02-06T02:55:04Z

Newacct:

{{Documentation/DevGuide/TextTOC
|Text2b=block
|TextTables=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Text/Text Table Properties
|NextPage=Documentation/DevGuide/Text/Accessing Existing Tables
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Text/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Inserting Tables}}
To create and insert a new text table, a five-step procedure must be followed:

# Get the service manager of the text document, querying the document's factory interface <idl>com.sun.star.lang.XMultiServiceFactory</idl>.
# Order a new text table from the factory by its service name "<code>com.sun.star.text.TextTable</code>", using the factory method <code>createInstance()</code>.
# From the object received, query the <idl>com.sun.star.text.XTextTable</idl> interface that inherits from <idl>com.sun.star.text.XTextContent</idl>.
# If necessary, initialize the table with the number of rows and columns. For this purpose, <code>XTextTable</code> offers the <code>initialize()</code> method.
# Insert the table into the text using the <code>insertTextContent()</code> method at its <idl>com.sun.star.text.XText</idl> interface. The method <code>insertTextContent()</code> expects an <code>XTextContent</code> to insert. Since <code>XTextTable</code> inherits from <code>XTextContent</code>, pass the <code>XTextTable</code> interface retrieved previously.

You are now ready to get cells, fill in text, values and formulas and set the table and cell properties as needed.

In the following code sample, there is a small helper function to put random numbers between -1000 and 1000 into the table to demonstrate formulas:


/** This method returns a random double which isn't too high or too low
*/
protected double getRandomDouble()
{
return ((maRandom.nextInt() % 1000) * maRandom.nextDouble());
}

The following helper function inserts a string into a cell known by its name and sets its text color to white:


/** This method sets the text colour of the cell refered to by sCellName to white and inserts
the string sText in it
*/
public static void insertIntoCell(String sCellName, String sText, XTextTable xTable) {
// Access the XText interface of the cell referred to by sCellName
XText xCellText = (XText) UnoRuntime.queryInterface(
XText.class, xTable.getCellByName(sCellName));

// create a text cursor from the cells XText interface
XTextCursor xCellCursor = xCellText.createTextCursor();

// Get the property set of the cell's TextCursor
XPropertySet xCellCursorProps = (XPropertySet)UnoRuntime.queryInterface(
XPropertySet.class, xCellCursor);

try {
// Set the colour of the text to white
xCellCursorProps.setPropertyValue("CharColor", new Integer(16777215));
} catch (Exception e) {
e.printStackTrace(System.out);
}

// Set the text in the cell to sText
xCellText.setString(sText);
}

Using the above helper functions, create a text table and insert it into the text document.


/** This method shows how to create and insert a text table, as well as insert text and formulae
into the cells of the table
*/
protected void TextTableExample ()
{
try
{
// Create a new table from the document's factory
XTextTable xTable = (XTextTable) UnoRuntime.queryInterface(
XTextTable.class, mxDocFactory .createInstance(
"com.sun.star.text.TextTable" ) );

// Specify that we want the table to have 4 rows and 4 columns
xTable.initialize( 4, 4 );

// Insert the table into the document
mxDocText.insertTextContent( mxDocCursor, xTable, false);
// Get an XIndexAccess of the table rows
XIndexAccess xRows = xTable.getRows();

// Access the property set of the first row (properties listed in service description:
// com.sun.star.text.TextTableRow)
XPropertySet xRow = (XPropertySet) UnoRuntime.queryInterface(
XPropertySet.class, xRows.getByIndex ( 0 ) );
// If BackTransparant is false, then the background color is visible
xRow.setPropertyValue( "BackTransparent", Boolean.FALSE);
// Specify the color of the background to be dark blue
xRow.setPropertyValue( "BackColor", new Integer(6710932));

// Access the property set of the whole table
XPropertySet xTableProps = (XPropertySet)UnoRuntime.queryInterface(
XPropertySet.class, xTable );
// We want visible background colors
xTableProps.setPropertyValue( "BackTransparent", Boolean.FALSE);
// Set the background colour to light blue
xTableProps.setPropertyValue( "BackColor", new Integer(13421823));

// set the text (and text colour) of all the cells in the first row of the table
insertIntoCell( "A1", "First Column", xTable );
insertIntoCell( "B1", "Second Column", xTable );
insertIntoCell( "C1", "Third Column", xTable );
insertIntoCell( "D1", "Results", xTable );

// Insert random numbers into the first this three cells of each
// remaining row
xTable.getCellByName( "A2" ).setValue( getRandomDouble() );
xTable.getCellByName( "B2" ).setValue( getRandomDouble() );
xTable.getCellByName( "C2" ).setValue( getRandomDouble() );

xTable.getCellByName( "A3" ).setValue( getRandomDouble() );
xTable.getCellByName( "B3" ).setValue( getRandomDouble() );
xTable.getCellByName( "C3" ).setValue( getRandomDouble() );

xTable.getCellByName( "A4" ).setValue( getRandomDouble() );
xTable.getCellByName( "B4" ).setValue( getRandomDouble() );
xTable.getCellByName( "C4" ).setValue( getRandomDouble() );

// Set the last cell in each row to be a formula that calculates
// the sum of the first three cells
xTable.getCellByName( "D2" ).setFormula( "sum <A2:C2>" );
xTable.getCellByName( "D3" ).setFormula( "sum <A3:C3>" );
xTable.getCellByName( "D4" ).setFormula( "sum <A4:C4>" );
}
catch (Exception e)
{
e.printStackTrace ( System.out );
}
}

The next sample inserts auto text entries into a table, splitting cells during its course.


/** This example demonstrates the use of the AutoTextContainer, AutoTextGroup and AutoTextEntry services
and shows how to create, insert and modify auto text blocks
*/
protected void AutoTextExample ()
{
try
{
// Go to the end of the document
mxDocCursor.gotoEnd( false );
// Insert two paragraphs
mxDocText.insertControlCharacter ( mxDocCursor,
ControlCharacter.PARAGRAPH_BREAK, false );
mxDocText.insertControlCharacter ( mxDocCursor,
ControlCharacter.PARAGRAPH_BREAK, false );
// Position the cursor in the second paragraph
XParagraphCursor xParaCursor = (XParagraphCursor) UnoRuntime.queryInterface(
XParagraphCursor.class, mxDocCursor );
xParaCursor.gotoPreviousParagraph ( false );

// Get an XNameAccess interface to all auto text groups from the document factory
XNameAccess xContainer = (XNameAccess) UnoRuntime.queryInterface(
XNameAccess.class, mxFactory.createInstance (
"com.sun.star.text.AutoTextContainer" ) );

// Create a new table at the document factory
XTextTable xTable = (XTextTable) UnoRuntime.queryInterface(
XTextTable.class, mxDocFactory .createInstance(
"com.sun.star.text.TextTable" ) );

// Store the names of all auto text groups in an array of strings
String[] aGroupNames = xContainer.getElementNames();

// Make sure we have at least one group name
if ( aGroupNames.length > 0 )
{
// initialise the table to have a row for every autotext group
//in a single column + one
// additional row for a header
xTable.initialize( aGroupNames.length+1,1);

// Access the XPropertySet of the table
XPropertySet xTableProps = (XPropertySet)UnoRuntime.queryInterface(
XPropertySet.class, xTable );

// We want a visible background
xTableProps.setPropertyValue( "BackTransparent", Boolean.FALSE);

// We want the background to be light blue
xTableProps.setPropertyValue( "BackColor", new Integer(13421823));

// Insert the table into the document
mxDocText.insertTextContent( mxDocCursor, xTable, false);

// Get an XIndexAccess to all table rows
XIndexAccess xRows = xTable.getRows();

// Get the first row in the table
XPropertySet xRow = (XPropertySet) UnoRuntime.queryInterface(
XPropertySet.class, xRows.getByIndex ( 0 ) );

// We want the background of the first row to be visible too
xRow.setPropertyValue( "BackTransparent", Boolean.FALSE);

// And let's make it dark blue
xRow.setPropertyValue( "BackColor", new Integer(6710932));

// Put a description of the table contents into the first cell
insertIntoCell( "A1", "AutoText Groups", xTable);

// Create a table cursor pointing at the second cell in the first column
XTextTableCursor xTableCursor = xTable.createCursorByCellName ( "A2" );

// Loop over the group names
for ( int i = 0 ; i < aGroupNames.length ; i ++ )
{
// Get the name of the current cell
String sCellName = xTableCursor.getRangeName ();

// Get the XText interface of the current cell
XText xCellText = (XText) UnoRuntime.queryInterface (
XText.class, xTable.getCellByName ( sCellName ) );

// Set the cell contents of the current cell to be
//the name of the of an autotext group
xCellText.setString ( aGroupNames[i] );

// Access the autotext gruop with this name
XAutoTextGroup xGroup = ( XAutoTextGroup ) UnoRuntime.queryInterface (
XAutoTextGroup.class,xContainer.getByName(aGroupNames[i]));

// Get the titles of each autotext block in this group
String [] aBlockNames = xGroup.getTitles();

// Make sure that the autotext group contains at least one block
if ( aBlockNames.length > 0 )
{
// Split the current cell vertically into two seperate cells
xTableCursor.splitRange ( (short) 1, false );

// Put the cursor in the newly created right hand cell
// and select it
xTableCursor.goRight ( (short) 1, false );

// Split this cell horizontally to make a seperate cell
// for each Autotext block
if ( ( aBlockNames.length -1 ) > 0 )
xTableCursor.splitRange (
(short) (aBlockNames.length - 1), true );

// loop over the block names
for ( int j = 0 ; j < aBlockNames.length ; j ++ )
{
// Get the XText interface of the current cell
xCellText = (XText) UnoRuntime.queryInterface (
XText.class, xTable.getCellByName (
xTableCursor.getRangeName() ) );

// Set the text contents of the current cell to the
// title of an Autotext block
xCellText.setString ( aBlockNames[j] );

// Move the cursor down one cell
xTableCursor.goDown( (short)1, false);
}
}
// Go back to the cell we originally split
xTableCursor.gotoCellByName ( sCellName, false );

// Go down one cell
xTableCursor.goDown( (short)1, false);
}

XAutoTextGroup xGroup;
String [] aBlockNames;

// Add a depth so that we only generate 200 numbers before
// giving up on finding a random autotext group that contains autotext blocks
int nDepth = 0;
do
{
// Generate a random, positive number which is lower than
// the number of autotext groups
int nRandom = Math.abs ( maRandom.nextInt() % aGroupNames.length );

// Get the autotext group at this name
xGroup = ( XAutoTextGroup ) UnoRuntime.queryInterface (
XAutoTextGroup.class, xContainer.getByName (
aGroupNames[ nRandom ] ) );

// Fill our string array with the names of all the blocks in this
// group
aBlockNames = xGroup.getElementNames();

// increment our depth counter
++nDepth;
}
while ( nDepth < 200 && aBlockNames.length == 0 );
// If we managed to find a group containg blocks...
if ( aBlockNames.length > 0 )
{
// Pick a random block in this group and get it's
// XAutoTextEntry interface
int nRandom = Math.abs ( maRandom.nextInt()
% aBlockNames.length );
XAutoTextEntry xEntry = ( XAutoTextEntry )
UnoRuntime.queryInterface (
XAutoTextEntry.class, xGroup.getByName (
aBlockNames[ nRandom ] ) );
// insert the modified autotext block at the end of the document
xEntry.applyTo ( mxDocCursor );

// Get the titles of all text blocks in this AutoText group
String [] aBlockTitles = xGroup.getTitles();

// Get the XNamed interface of the autotext group
XNamed xGroupNamed = ( XNamed ) UnoRuntime.queryInterface (
XNamed.class, xGroup );

// Output the short cut and title of the random block
//and the name of the group it's from
System.out.println ( "Inserted the Autotext '" + aBlockTitles[nRandom]
+ "', shortcut '" + aBlockNames[nRandom] + "' from group '"
+ xGroupNamed.getName() );
}
}

// Go to the end of the document
mxDocCursor.gotoEnd( false );
// Insert new paragraph
mxDocText.insertControlCharacter (
mxDocCursor, ControlCharacter.PARAGRAPH_BREAK, false );

// Position cursor in new paragraph
xParaCursor.gotoPreviousParagraph ( false );

// Insert a string in the new paragraph
mxDocText.insertString ( mxDocCursor, "Some text for a new autotext block", false );

// Go to the end of the document
mxDocCursor.gotoEnd( false );
}
catch (Exception e)
{
e.printStackTrace ( System.out );
}
}

{{PDL1}}

[[Category:Documentation/Developer's Guide/Text Documents]]

Documentation/DevGuide/Drawings/Presentation Settings

2010-02-06T02:44:32Z

Newacct:

{{Documentation/DevGuide/DrawingsTOC
|Drawing2e=block
|DrawingPresSetting=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Drawings/Working with Presentation Documents
|NextPage=Documentation/DevGuide/Drawings/Custom Slide Show
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Drawings/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Presentation Settings}}

Impress documents contain a Presentation service that controls a running presentation. This <idl>com.sun.star.presentation.Presentation</idl> service can be accessed through the <idl>com.sun.star.presentation.XPresentationSupplier</idl> interface through the method:

<source lang="idl">
com::sun::star::presentation::XPresentation getPresentation()
</source>

The method <code>getPresentation()</code> returns a <idl>com.sun.star.presentation.Presentation</idl> service. It contains properties for presentation settings and the interface <idl>com.sun.star.presentation.XPresentation</idl>.

The presentation settings define the slide range, which custom show is used, and how the presentation is executed. These settings are provided as properties of the service <idl>com.sun.star.presentation.Presentation</idl>. This service also exports the <idl>com.sun.star.presentation.XPresentation</idl> interface that starts and ends a presentation.

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
!colspan="2"|Methods of <idl>com.sun.star.presentation.XPresentation</idl>
|-
|<idlm>com.sun.star.presentation.XPresentation:start</idlm>()
|Starts the presentation in full-screen mode.
|-
|<idlm>com.sun.star.presentation.XPresentation:end</idlm>()
|Stops the presentation.
|-
|<idlm>com.sun.star.presentation.XPresentation:rehearseTimings</idlm>()
|Starts the presentation from the beginning and shows the actual running time to the user.
|}

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
!colspan="2"|Properties of <idl>com.sun.star.presentation.Presentation</idl>
|-
|<idlm>com.sun.star.presentation.Presentation:AllowAnimations</idlm>
|<code>boolean</code> - Enables/disables the shape animations.
|-
|<idlm>com.sun.star.presentation.Presentation:CustomShow</idlm>
|<code>string</code> - Contains the name of a customized show that is used for the presentation.
|-
|[http://api.openoffice.org/docs/common/ref/com/sun/star/presentation/Presentation.html#FirstPage Presentation:FirstPage]
|<code>string</code> - Contains the name of the page where the presentation is started.
|-
|<idlm>com.sun.star.presentation.Presentation:IsAlwaysOnTop</idlm>
|<code>boolean</code> - If true, the window of the presentation is always on top of all the other windows.
|-
|<idlm>com.sun.star.presentation.Presentation:IsAutomatic</idlm>
|<code>boolean</code> - If true, all pages are changed automatically.
|-
|<idlm>com.sun.star.presentation.Presentation:IsEndless</idlm>
|<code>boolean</code> - If true, the presentation is repeated endlessly.
|-
|<idlm>com.sun.star.presentation.Presentation:IsFullScreen</idlm>
|<code>boolean</code> - If true, the presentation runs in full-screen mode.
|-
|<idlm>com.sun.star.presentation.Presentation:IsLivePresentation</idlm>
|<code>boolean</code> - With this property, the presentation is set to live mode.
|-
|<idlm>com.sun.star.presentation.Presentation:IsMouseVisible</idlm>
|<code>boolean</code> - If true, the mouse is visible during the presentation.
|-
|<idlm>com.sun.star.presentation.Presentation:Pause</idlm>
|<code>long</code> - Duration of the black screen after the presentation has finished.
|-
|<idlm>com.sun.star.presentation.Presentation:StartWithNavigator</idlm>
|<code>boolean</code> - If true, the Navigator is opened at the start of the presentation.
|-
|<idlm>com.sun.star.presentation.Presentation:UsePen</idlm>
|<code>boolean</code> - If true, a pen is shown during presentation.
|-
|<idlm>com.sun.star.presentation.Presentation:IsShowAll</idlm>
|<code>boolean</code> - Show all slides.
|-
|<idlm>com.sun.star.presentation.Presentation:IsShowLogo</idlm>
|<code>boolean</code> - Show {{PRODUCTNAME}} logo on pause page in automatic mode.
|-
|<idlm>com.sun.star.presentation.Presentation:IsTransitionOnClick</idlm>
|<code>boolean</code> - Slide change on mouse click, in addition to pressing cursor right.
|}


The properties <code>IsShowAll</code>, <code>IsShowLogo</code> and <code>IsTransitionOnClick</code> are currently not documented in the API reference.

The next example demonstrates how to start a presentation that is automatically repeated and plays in full-screen mode by modifying the presentation settings.


<source lang="java">
XPresentationSupplier xPresSupplier = (XPresentationSupplier)UnoRuntime.queryInterface(
XPresentationSupplier.class, xComponent);
XPresentation xPresentation = xPresSupplier.getPresentation();
XPropertySet xPresPropSet = (XPropertySet)UnoRuntime.queryInterface(
XPropertySet.class, xPresentation);
xPresPropSet.setPropertyValue("IsEndless", Boolean.TRUE);
xPresPropSet.setPropertyValue("IsFullScreen", Boolean.TRUE);
xPresPropSet.setPropertyValue("Pause", new Integer(0));
xPresentation.start();
</source>

{{PDL1}}

[[Category:Documentation/Developer's Guide/Drawing Documents and Presentation Documents]]

Documentation/DevGuide/WritingUNO/Disable Commands

2010-02-05T09:03:05Z

Newacct:

{{Documentation/DevGuide/WritingUNOTOC
|WritingUNO2e=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/WritingUNO/AddOns/Installation
|NextPage=Documentation/DevGuide/WritingUNO/Intercepting Context Menus
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/WritingUNO/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Disable Commands}}
In {{PRODUCTNAME}}, there may be situations where functions should be disabled to prevent users from changing or destroying documents inadvertently. {{PRODUCTNAME}} maintains a list of disabled commands that can be maintained by users and developers through the configuration API.

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

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

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

[[Image:DisableCommands_ApplicationFlow.png|none|thumb|400px|How the disable commands feature works]]

{{Documentation/Caution|Since the disable commands implementation is the first part in the dispatch chain, there is no way to circumvent it. The disabled command must be removed from the list, otherwise it remains disabled.}}

=== Configuration ===

The disable commands feature uses the configuration branch ''org.openoffice.Office.Commands'' to read which commands should be disabled. The following schema applies:
<source lang="xml">
<?xml version='1.0' encoding='UTF-8'?>
<oor:component-schema oor:name="Commands" oor:package="org.openoffice.Office" xml:lang="en-US" xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<templates>
<group oor:name="CommandType">
<prop oor:name="Command" oor:type="xs:string"/>
</group>
</templates>
<component>
<group oor:name="Execute">
<set oor:name="Disabled" oor:node-type="CommandType"/>
</group>
</component>
</oor:component-schema>
</source>
The configuration schema for disabled commands is very simple. The ''org.openoffice.Office.Commands'' branch has a group called <code>Execute</code>. This group has only one set called <code>Disabled</code>. The <code>Disabled</code> set supports nodes of the type <code>CommandType</code>. The following table describes the supported properties of <code>CommandType</code>.

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
!colspan="2"|Properties of the <code>CommandType</code> group
|-
|<code>oor:component-data</code>
|string. It must be unique inside the <code>Disabled</code> set, but has no additional meaning for the implementation of the disable commands feature. Use a consecutive numbering scheme; even numbers are allowed.
|-
|<code>Command</code>
|string. This is the command name with the preceding protocol. That means the command URL ''.uno:Open'' (which shows the '''File – Open''' dialog) must be written as <code>Open</code>.
The valid commands can be found in the document ''Index of Command Names'' in the [http://framework.openoffice.org/servlets/ProjectDocumentList Documentation section of the framework project] on the OpenOffice.org web page. The {{PRODUCTNAME}} SDK also includes the latest [http://www.openoffice.org/files/documents/25/60/commands_11beta.html list of command names].
Additional information regarding Command names is available in: [http://wiki.services.openoffice.org/wiki/Framework/Article/OpenOffice.org_2.x_Commands]
|}

The example below shows a configuration file that disables the commands for '''File – Open''', '''Edit – Select All''', '''Help – About {{PRODUCTNAME}}''' and '''File – Exit'''.
<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<oor:component-data oor:name="Commands" oor:package="org.openoffice.Office" xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<node oor:name="Execute">
<node oor:name="Disabled">
<node oor:name="com.mycompany.a-chosen-unique-name.m1" oor:op="replace">
<prop oor:name="Command">
<value>Open</value>
</prop>
</node>
<node oor:name="com.mycompany.a-chosen-unique-name.m2" oor:op="replace">
<prop oor:name="Command">
<value>SelectAll</value>
</prop>
</node>
<node oor:name="com.mycompany.a-chosen-unique-name.m3" oor:op="replace">
<prop oor:name="Command">
<value>About</value>
</prop>
</node>
<node oor:name="com.mycompany.a-chosen-unique-name.m4" oor:op="replace">
<prop oor:name="Command">
<value>Quit</value>
</prop>
</node>
</node>
</node>
</oor:component-data>
</source>

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

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

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

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

=== Disabling Commands at Runtime ===


The following code example first removes all commands that were defined in the user layer of the configuration branch <code>org.openoffice.Office.Commands</code> as having a defined starting point. Then it checks if it can get dispatch objects for some pre-defined commands.Then the example disables these commands and tries to get dispatch objects for them again. At the end, the code removes the disabled commands again, otherwise {{PRODUCTNAME}} would not be fully usable any longer.
<source lang="java">
import com.sun.star.bridge.XUnoUrlResolver;
import com.sun.star.uno.UnoRuntime;
import com.sun.star.uno.XComponentContext;
import com.sun.star.lang.XMultiComponentFactory;
import com.sun.star.beans.XPropertySet;
import com.sun.star.beans.PropertyValue;
import com.sun.star.lang.XMultiServiceFactory;
import com.sun.star.lang.XSingleServiceFactory;
import com.sun.star.util.XURLTransformer;
import com.sun.star.frame.XDesktop;

import com.sun.star.beans.UnknownPropertyException;

/*
* Provides example code how to enable/disable
* commands.
*/
public class DisableCommandsTest extends java.lang.Object {

/*
* A list of command names
*/
final static private String[] aCommandURLTestSet =
{
"Open",
"About",
"SelectAll",
"Quit",
};

private static XComponentContext xRemoteContext = null;
private static XMultiComponentFactory xRemoteServiceManager = null;
private static XURLTransformer xTransformer = null;
private static XMultiServiceFactory xConfigProvider = null;

/*
* @param args the command line arguments
*/
public static void main(String[] args) {

try {
// connect
XComponentContext xLocalContext =
com.sun.star.comp.helper.Bootstrap.createInitialComponentContext(null);
XMultiComponentFactory xLocalServiceManager = xLocalContext.getServiceManager();
Object urlResolver = xLocalServiceManager.createInstanceWithContext(
"com.sun.star.bridge.UnoUrlResolver", xLocalContext);
XUnoUrlResolver xUnoUrlResolver = (XUnoUrlResolver) UnoRuntime.queryInterface(
XUnoUrlResolver.class, urlResolver );
Object initialObject = xUnoUrlResolver.resolve(
"uno:socket,host=localhost,port=2083;urp;StarOffice.ServiceManager");
XPropertySet xPropertySet = (XPropertySet)UnoRuntime.queryInterface(
XPropertySet.class, initialObject);
Object context = xPropertySet.getPropertyValue("DefaultContext");
xRemoteContext = (XComponentContext)UnoRuntime.queryInterface(
XComponentContext.class, context);
xRemoteServiceManager = xRemoteContext.getServiceManager();
Object transformer = xRemoteServiceManager.createInstanceWithContext(
"com.sun.star.util.URLTransformer", xRemoteContext);
xTransformer = (com.sun.star.util.XURLTransformer)UnoRuntime.queryInterface(
com.sun.star.util.XURLTransformer.class, transformer);

Object configProvider = xRemoteServiceManager.createInstanceWithContext(
"com.sun.star.configuration.ConfigurationProvider", xRemoteContext);
xConfigProvider = (com.sun.star.lang.XMultiServiceFactory)UnoRuntime.queryInterface(
com.sun.star.lang.XMultiServiceFactory.class, configProvider);

// First we need a defined starting point. So we have to remove
// all commands from the disabled set!
enableCommands();

// Check if the commands are usable
testCommands(false);

// Disable the commands
disableCommands();

// Now the commands should not be usable anymore
testCommands(true);

// Remove disable commands to make Office usable again
enableCommands();
}
catch (java.lang.Exception e){
e.printStackTrace();
}
finally {
System.exit(0);
}
}

/**
* Test the commands that we enabled/disabled
*/
private static void testCommands(boolean bDisabledCmds) throws com.sun.star.uno.Exception {
// We need the desktop to get access to the current frame
Object desktop = xRemoteServiceManager.createInstanceWithContext(
"com.sun.star.frame.Desktop", xRemoteContext );
com.sun.star.frame.XDesktop xDesktop = (com.sun.star.frame.XDesktop)UnoRuntime.queryInterface(
com.sun.star.frame.XDesktop.class, desktop);
com.sun.star.frame.XFrame xFrame = xDesktop.getCurrentFrame();
com.sun.star.frame.XDispatchProvider xDispatchProvider = null;
if (xFrame != null) {
// We have a frame. Now we need access to the dispatch provider.
xDispatchProvider = (com.sun.star.frame.XDispatchProvider)UnoRuntime.queryInterface(
com.sun.star.frame.XDispatchProvider.class, xFrame );
if (xDispatchProvider != null) {
// As we have the dispatch provider we can now check if we get a dispatch
// object or not.
for (int n = 0; n < aCommandURLTestSet.length; n++) {
// Prepare the URL
com.sun.star.util.URL[] aURL = new com.sun.star.util.URL[1];
aURL[0] = new com.sun.star.util.URL();
com.sun.star.frame.XDispatch xDispatch = null;

aURL[0].Complete = ".uno:" + aCommandURLTestSet[n];
xTransformer.parseSmart(aURL, ".uno:");

// Try to get a dispatch object for our URL
xDispatch = xDispatchProvider.queryDispatch(aURL[0], "", 0);

if (xDispatch != null) {
if (bDisabledCmds)
System.out.println("Something is wrong, I got dispatch object for "
+ aURL[0].Complete);
else
System.out.println("Ok, dispatch object for " + aURL[0].Complete);
}
else {
if (!bDisabledCmds)
System.out.println("Something is wrong, I cannot get dispatch object for "
+ aURL[0].Complete);
else
System.out.println("Ok, no dispatch object for " + aURL[0].Complete);
}
resetURL(aURL[0]);
}
}
else
System.out.println("Couldn't get XDispatchProvider from Frame!");
}
else
System.out.println("Couldn't get current Frame from Desktop!");
}

/**
* Ensure that there are no disabled commands in the user layer. The
* implementation removes all commands from the disabled set!
*/
private static void enableCommands() {
// Set the root path for our configuration access
com.sun.star.beans.PropertyValue[] lParams = new com.sun.star.beans.PropertyValue[1];

lParams[0] = new com.sun.star.beans.PropertyValue();
lParams[0].Name = "nodepath";
lParams[0].Value = "/org.openoffice.Office.Commands/Execute/Disabled";

try {
// Create configuration update access to have write access to the configuration
Object xAccess = xConfigProvider.createInstanceWithArguments(
"com.sun.star.configuration.ConfigurationUpdateAccess", lParams);

com.sun.star.container.XNameAccess xNameAccess = (com.sun.star.container.XNameAccess)
UnoRuntime.queryInterface(com.sun.star.container.XNameAccess.class, xAccess);
if (xNameAccess != null) {
// We need the XNameContainer interface to remove the nodes by name
com.sun.star.container.XNameContainer xNameContainer =
(com.sun.star.container.XNameContainer)
UnoRuntime.queryInterface(com.sun.star.container.XNameContainer.class, xAccess);

// Retrieves the names of all Disabled nodes
String[] aCommandsSeq = xNameAccess.getElementNames();
for (int n = 0; n < aCommandsSeq.length; n++) {
try {
// remove the node
xNameContainer.removeByName( aCommandsSeq[n]);
}
catch (com.sun.star.lang.WrappedTargetException e) {
}
catch (com.sun.star.container.NoSuchElementException e) {
}
}
}

// Commit our changes
com.sun.star.util.XChangesBatch xFlush =
(com.sun.star.util.XChangesBatch)UnoRuntime.queryInterface(
com.sun.star.util.XChangesBatch.class, xAccess);
xFlush.commitChanges();
}
catch (com.sun.star.uno.Exception e) {
System.out.println("Exception detected!");
System.out.println(e);
}
}

/**
* Disable all commands defined in the aCommandURLTestSet array
*/
private static void disableCommands() {
// Set the root path for our configuration access
com.sun.star.beans.PropertyValue[] lParams = new com.sun.star.beans.PropertyValue[1];
lParams[0] = new com.sun.star.beans.PropertyValue();
lParams[0].Name = "nodepath";
lParams[0].Value = "/org.openoffice.Office.Commands/Execute/Disabled";

try {
// Create configuration update access to have write access to the configuration
Object xAccess = xConfigProvider.createInstanceWithArguments(
"com.sun.star.configuration.ConfigurationUpdateAccess", lParams);

com.sun.star.lang.XSingleServiceFactory xSetElementFactory =
(com.sun.star.lang.XSingleServiceFactory)UnoRuntime.queryInterface(
com.sun.star.lang.XSingleServiceFactory.class, xAccess);

com.sun.star.container.XNameContainer xNameContainer =
(com.sun.star.container.XNameContainer)UnoRuntime.queryInterface(
com.sun.star.container.XNameContainer.class, xAccess );

if (xSetElementFactory != null && xNameContainer != null) {
Object[] aArgs = new Object[0];

for (int i = 0; i < aCommandURLTestSet.length; i++) {
// Create the nodes with the XSingleServiceFactory of the configuration
Object xNewElement = xSetElementFactory.createInstanceWithArguments( aArgs );
if (xNewElement != null) {
// We have a new node. To set the properties of the node we need
// the XPropertySet interface.
com.sun.star.beans.XPropertySet xPropertySet =
(com.sun.star.beans.XPropertySet)UnoRuntime.queryInterface( com.sun.star.beans.XPropertySet.class,
xNewElement );

if (xPropertySet != null) {
// Create a unique node name.
String aCmdNodeName = "Command-";
aCmdNodeName += i;

// Insert the node into the Disabled set
xPropertySet.setPropertyValue("Command", aCommandURLTestSet[i]);
xNameContainer.insertByName(aCmdNodeName, xNewElement);
}
}
}

// Commit our changes
com.sun.star.util.XChangesBatch xFlush = (com.sun.star.util.XChangesBatch)
UnoRuntime.queryInterface(com.sun.star.util.XChangesBatch.class, xAccess);
xFlush.commitChanges();
}
}
catch (com.sun.star.uno.Exception e) {
System.out.println("Exception detected!");
System.out.println(e);
}
}

/**
* reset URL so it can be reused
*
* @param aURL
* the URL that should be reseted
*/
private static void resetURL(com.sun.star.util.URL aURL) {
aURL.Protocol = "";
aURL.User = "";
aURL.Password = "";
aURL.Server = "";
aURL.Port = 0;
aURL.Path = "";
aURL.Name = "";
aURL.Arguments = "";
aURL.Mark = "";
aURL.Main = "";
aURL.Complete = "";
}
}
</source>
{{PDL1}}

[[Category:Documentation/Developer's Guide/Writing UNO Components]]

Documentation/DevGuide/WritingUNO/Possible Structures for Java Components

2010-02-05T06:27:49Z

Newacct:

{{Documentation/DevGuide/WritingUNOTOC
|WritingUNO2c=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/WritingUNO/Create Instance with Arguments
|NextPage=Documentation/DevGuide/WritingUNO/Running and Debugging Java Components
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/WritingUNO/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Possible Structures for Java Components}}
__NOTOC__
The implementation of a component depends on the needs of the implementer. The following examples show some possible ways to assemble a component. There can be one implemented object or several implemented objects per component file.

=== One Implementation per Component File ===

There are additional options if implementing one service per component file:

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

==== Implementation Class with Component Operations ====

An implementation class contains the static component operations. The following sample implements an interface <code>com.sun.star.test.XSomething</code> in an implementation class <code>JavaComp.TestComponent</code>:
<source lang="idl">
// UNOIDL: interface example specification
module com { module sun { module star { module test {

interface XSomething: com::sun::star::uno::XInterface
{
string methodOne([in]string val);
};
}; }; }; };
</source>
A component that implements only one service supporting <code>XSomething</code> can be assembled in one class as follows:
<source lang="java">
package JavaComp;

...

public class TestComponent implements XSomething, XTypeProvider, XServiceInfo {

public static final String __serviceName="com.sun.star.test.JavaTestComponent";

public static XSingleServiceFactory __getServiceFactory(String implName,
XMultiServiceFactory multiFactory, XRegistryKey regKey) {
XSingleServiceFactory xSingleServiceFactory = null;

if (implName.equals( TestComponent.class.getName()) )
xSingleServiceFactory = FactoryHelper.getServiceFactory( TestComponent.class,
TestComponent.__serviceName, multiFactory, regKey);
return xSingleServiceFactory;
}

public static boolean __writeRegistryServiceInfo(XRegistryKey regKey){
return FactoryHelper.writeRegistryServiceInfo( TestComponent.class.getName(),
TestComponent.__serviceName, regKey);
}

// XSomething
string methodOne(String val) {
return val;
}
//XTypeProvider
public com.sun.star.uno.Type[] getTypes( ) {
...
}
// XTypeProvider
public byte[] getImplementationId( ) {
...
}
//XServiceInfo
public String getImplementationName( ) {
...
}
// XServiceInfo
public boolean supportsService( /*IN*/String serviceName ) {
...
}
//XServiceInfo
public String[] getSupportedServiceNames( ) {
...
}
}
</source>
The class implements the <code>XSomething</code> interface. The IDL description and documentation provides information about its functionality. The class also contains the functions for factory creation and registration, therefore the manifest entry must read as follows:

RegistrationClassName: JavaComp.TestComponent

==== Implementation Class with Component Operations and Inner Implementation Class ====
To implement the component as inner class of the one that provides the service factory through <code>__getServiceFactory()</code>, it must be a ''static'' inner class, otherwise the factory provided by the <code>FactoryHelper</code> cannot create the component. An example for an inner implementation class is located in the sample <code>com.sun.star.comp.demo.DemoComponent.java</code> provided with the SDK. The implementation of <code>__getServiceFactory()</code> and <code>__writeRegistryServiceInfo()</code> is omitted here, because they act the same as in the implementation class with component operations above.
<source lang="java">
package com.sun.star.comp.demo;

public class DemoComponent {

...
// static inner class implements service com.sun.star.demo.DemoComponent
static public class _Implementation implements XTypeProvider,
XServiceInfo, XInitialization, XWindowListener,
XActionListener, XTopWindowListener {

static private final String __serviceName = "com.sun.star.demo.DemoComponent";
private XMultiServiceFactory _xMultiServiceFactory;

// Constructor
public _Implementation(XMultiServiceFactory xMultiServiceFactory) {
}
}

// static method to get a single factory creating the given service from the factory helper
public static XSingleServiceFactory __getServiceFactory(String implName,
XMultiServiceFactory multiFactory,
XRegistryKey regKey) {
...
}

// static method to write the service information into the given registry key
public static boolean __writeRegistryServiceInfo(XRegistryKey regKey) {
...
}

}
</source>
The manifest entry for this implementation structure again has to point to the class with the static component operations:

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

=== Multiple Implementations per Component File ===

To assemble several service implementations in one component file, implement each service in its own class and add a separate class containing the static component operations. The following code sample features two services: <code>TestComponentA</code> and <code>TestComponentB</code> implementing the interfaces <code>XSomethingA</code> and <code>XSomethingB</code> with a separate static class <code>TestServiceProvider</code> containing the component operations.

The following are the UNOIDL specifications for <code>XSomethingA</code> and <code>XSomethingB</code>:
<source lang="idl">
module com { module sun { module star { module test {
interface XSomethingA: com::sun::star::uno::XInterface
{
string methodOne([in]string value);
};
}; }; }; };

module com { module sun { module star { module test {
interface XSomethingB: com::sun::star::uno::XInterface
{
string methodTwo([in]string value);
};
}; }; }; };
</source>
<code>TestComponentA</code> implements <code>XSomethingA</code>: 
<source lang="java">
package JavaComp;

public class TestComponentA implements XTypeProvider, XServiceInfo, XSomethingA {
static final String __serviceName= "JavaTestComponentA";

static byte[] _implementationId;

public TestComponentA() {
}

// XSomethingA
public String methodOne(String val) {
return val;
}

//XTypeProvider
public com.sun.star.uno.Type[] getTypes( ) {
Type[] retValue= new Type[3];
retValue[0]= new Type( XServiceInfo.class);
retValue[1]= new Type( XTypeProvider.class);
retValue[2]= new Type( XSomethingA.class);
return retValue;
}

//XTypeProvider
synchronized public byte[] getImplementationId( ) {
if (_implementationId == null) {
_implementationId= new byte[16];
int hash = hashCode();
_implementationId[0] = (byte)(hash & 0xff);
_implementationId[1] = (byte)((hash >>> 8) & 0xff);
_implementationId[2] = (byte)((hash >>> 16) & 0xff);
_implementationId[3] = (byte)((hash >>>24) & 0xff);
}
return _implementationId;
}

//XServiceInfo
public String getImplementationName( ) {
return getClass().getName();
}
// XServiceInfo
public boolean supportsService( /*IN*/String serviceName ) {
return serviceName.equals( __serviceName);
}

//XServiceInfo
public String[] getSupportedServiceNames( ) {
String[] retValue= new String[0];
retValue[0]= __serviceName;
return retValue;
}
}

</source>
<code>TestComponentB</code> implements <code>XSomethingB</code>. Note that it receives the component context and initialization arguments in its constructor. 
<source lang="java">
package JavaComp;

public class TestComponentB implements XTypeProvider, XServiceInfo, XSomethingB {
static final String __serviceName= "JavaTestComponentB";

static byte[] _implementationId;
private XComponentContext context;
private Object[] args;

public TestComponentB(XComponentContext context, Object[] args) {
this.context= context;
this.args= args;
}

// XSomethingB
public String methodTwo(String val) {
if (args.length > 0 && args[0] instanceof String )
return (String) args[0];
return val;
}

//XTypeProvider
public com.sun.star.uno.Type[] getTypes( ) {
Type[] retValue= new Type[3];
retValue[0]= new Type( XServiceInfo.class);
retValue[1]= new Type( XTypeProvider.class);
retValue[2]= new Type( XSomethingB.class);
return retValue;
}

//XTypeProvider
synchronized public byte[] getImplementationId( ) {
if (_implementationId == null) {
_implementationId= new byte[16];
int hash = hashCode();
_implementationId[0] = (byte)(hash & 0xff);
_implementationId[1] = (byte)((hash >>> 8) & 0xff);
_implementationId[2] = (byte)((hash >>> 16) & 0xff);
_implementationId[3] = (byte)((hash >>>24) & 0xff);
}
return _implementationId;
}

//XServiceInfo
public String getImplementationName( ) {
return getClass().getName();
}

// XServiceInfo
public boolean supportsService( /*IN*/String serviceName ) {
return serviceName.equals( __serviceName);
}

//XServiceInfo
public String[] getSupportedServiceNames( ) {
String[] retValue= new String[0];
retValue[0]= __serviceName;
return retValue;
}
}
</source>
<code>TestServiceProvider</code> implements <code>__getServiceFactory()</code> and <code>__writeRegistryServiceInfo()</code>:

<source lang="java">
package JavaComp;
...
public class TestServiceProvider
{
public static XSingleServiceFactory __getServiceFactory(String implName,
XMultiServiceFactory multiFactory,
XRegistryKey regKey) {
XSingleServiceFactory xSingleServiceFactory = null;

if (implName.equals( TestComponentA.class.getName()) )
xSingleServiceFactory = FactoryHelper.getServiceFactory( TestComponentA.class,
TestComponentA.__serviceName, multiFactory, regKey);
else if (implName.equals(TestComponentB.class.getName()))
xSingleServiceFactory= FactoryHelper.getServiceFactory( TestComponentB.class,
TestComponentB.__serviceName, multiFactory, regKey);
return xSingleServiceFactory;
}

public static boolean __writeRegistryServiceInfo(XRegistryKey regKey){
boolean bregA= FactoryHelper.writeRegistryServiceInfo( TestComponentA.class.getName(),
TestComponentA.__serviceName, regKey);
boolean bregB= FactoryHelper.writeRegistryServiceInfo( TestComponentB.class.getName(),
TestComponentB.__serviceName, regKey);
return bregA && bregB;
}
}
</source>
The corresponding manifest entry must point to the static class with the component operations, in this case <code>JavaComp.TestServiceProvider</code>:

RegistrationClassName: JavaComp.TestServiceProvider

=== Additional UNO Types ===

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

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

{{Documentation/Note|Note: For backwards compatibility, if you do not include the <tt>UNO-Type-Path</tt> manifest entry at all, the UNO runtime assumes that the current jar does contain UNO types.}}

{{PDL1}}

[[Category:Documentation/Developer's Guide/Writing UNO Components]]

Calc/Add-In/CompleteAddIn

2010-02-05T05:20:06Z

Newacct:

{{Documentation/Candidate}}
=An other C++ add-in example=
In this article under construction, a complete and simple add-in in C++ is presented.
==Introduction==
Before reading this article, please read [[Constructing_Components|Constructing Components]] and [[SimpleCalcAddIn]]. In SimpleCalcAddin you will learn most of important things like the tools involved in constructing an addin, the services involved and also the corresponding references to read in the devlopper's guide.

Let's recall here how different files are created and what are the corresponding tools involved ? A drawing is beter than a long discussion :

[[Image:ComponentTools.png]]

As you can see idlc is used to transform a .IDL-suffix file into a .urd-suffix file, regmerge to transform the previous .urd-suffix file into a .rdb-suffix file and so on... (see the corresponding [[SimpleCalcAddIn#Other_Files|SimpleCalcAddin]] compilation script and also [[Constructing_Components#Compilation_Chain_of_a_Component|Compilation Chain of a Component]]. The action done by the red arrow is not a file transformation but what is usually called registery. Before going further let's note that starting from an idl file, we will generate an hpp file : this file automatically defines a C++ class that we will use in the cxx file.

You can go further with component and Java [[JavaEclipseTuto|here]].

We choose here an other way : starting from an example of SDK slightly modified :
<OpenOffice.org1.1_SDK>/examples/DevelopersGuide/Components/CppComponent

I mean I will use this example makefile only modified to take into account the fact I only use one file instead the two provided by the example. The makefile compiles the component and installs it.

==IDL File==
We begin with a simple IDL file with four methods. Here is the corresponding IDL file :
<source lang="idl">
// IDL
#include <com/sun/star/uno/XInterface.idl>
#include <com/sun/star/lang/XInitialization.idl>
#include <com/sun/star/lang/XServiceName.idl>
#include <com/sun/star/lang/XLocalizable.idl>
#include <com/sun/star/sheet/XAddIn.idl>
module my_module
{
interface XSomething : com::sun::star::uno::XInterface
{ // our four methods
string methodOne( [in] string val );
string methodTwo( [in] string val );
long methodThree( [in] sequence< sequence< long > > aValList );
sequence< sequence< long > > methodFour( [in] sequence< sequence< long > > aValList );
};
service MyService2
{
interface XSomething;
interface com::sun::star::lang::XInitialization;
interface com::sun::star::lang::XServiceName;
interface com::sun::star::sheet::XAddIn;
};
};
</source>

Four methods named methodOne, methodTwo, methodThree and methodFour can be seen in this IDL file and then will be implemented.

We give the automatically generated C++ class with the cppumaker tool.
<source lang="cpp">
class SAL_NO_VTABLE XSomething : public ::com::sun::star::uno::XInterface
{
public:

// Methods
virtual ::rtl::OUString SAL_CALL methodOne( const ::rtl::OUString& val ) throw
(::com::sun::star::uno::RuntimeException) = 0;
virtual ::rtl::OUString SAL_CALL methodTwo( const ::rtl::OUString& val ) throw
(::com::sun::star::uno::RuntimeException) = 0;
virtual sal_Int32 SAL_CALL methodThree( const ::com::sun::star::uno::Sequence<
::com::sun::star::uno::Sequence< sal_Int32 > >& aValList ) throw
(::com::sun::star::uno::RuntimeException) = 0;
virtual ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Sequence<
sal_Int32 > > SAL_CALL methodFour( const ::com::sun::star::uno::Sequence<
::com::sun::star::uno::Sequence< sal_Int32 > >& aValList ) throw
(::com::sun::star::uno::RuntimeException) = 0;
};
</source>

where again the four methods are seen but in C++ language. Note before going further that parameters of the methods are always marked as const but passed by reference (in C++ style with & operator). It's time to give the corresponding code.

==Implementing in C++ the corresponding four member Functions==
We first give the C++ code of the four methods presented in the previous IDL file.

===The two first member functions===
The two first methods are similar :
<source lang="cpp">
// C++
OUString MyService2Impl::methodOne( OUString const & str )
throw (RuntimeException)
{
return OUString( RTL_CONSTASCII_USTRINGPARAM(
"called methodOne() of MyService2 implementation: ") ) + m_arg + str;
}

OUString MyService2Impl::methodTwo( OUString const & str )throw (RuntimeException)
{
return OUString( RTL_CONSTASCII_USTRINGPARAM(
"called methodTwo() of MyService2 implementation: ") ) + m_arg + str;
}
</source>
They only take a string (from a OOoCalc Cell) and add a message and put all the message+string in the result cell.

===The third member Function===
The third member function is more complicated : it returns a value calculed from a cell range (the sum).
<source lang="cpp">
// C++
sal_Int32 MyService2Impl::methodThree(const Sequence< Sequence< sal_Int32 > > &aValList )
throw (RuntimeException)
{
sal_Int32 n1 = 0;
sal_Int32 n2 = 0;
sal_Int32 nE1 = aValList.getLength();
sal_Int32 nE2 = 0;
sal_Int32 temp=0;
for( n1 = 0 ; n1 < nE1 ; n1++ )
{
const Sequence< sal_Int32 > rList = aValList[ n1 ];
nE2 = rList.getLength();
const sal_Int32* pList = rList.getConstArray();
for( n2 = 0 ; n2 < nE2 ; n2++ )
{
temp += pList[ n2 ];
}
}
return temp;
}
</source>

===The fourth member Function===
The goal of the fourth member function is to show how we can implement a matrix function : starting from a cell range and obtaining a cell range.
<source lang="cpp">
//C++
//It's a matrix operation should be called like : {=METHODFOUR(A1:B4)}
Sequence< Sequence< sal_Int32 > > MyService2Impl::methodFour(const Sequence< Sequence< sal_Int32 > > &aValList )
throw (RuntimeException)
{ sal_Int32 n1, n2;
sal_Int32 nE1 = aValList.getLength();
sal_Int32 nE2;
Sequence< Sequence< sal_Int32 > > temp = aValList;
for( n1 = 0 ; n1 < nE1 ; n1++ )
{
Sequence< sal_Int32 > rList = temp[ n1 ];
nE2 = rList.getLength();
for( n2 = 0 ; n2 < nE2 ; n2++ )
{
rList[ n2 ] += 4;
}
temp[n1]=rList;
}
return temp;
}
</source>
What is done by this example is not great : only add four to every cells of the cell range and put the result in an other cell range.

Every method are related to a C++ class named MyService2Impl. Let's now give the corresponding class definition.

===The C++ Class===
We use an helper to implement our class and then we don't need to implement all the interfaces : no need to implement XInterface, XTypeProvider, XWeak for instance. We give now the corresponding C++ code.
<source lang="cpp">
//C++
class MyService2Impl : public ::cppu::WeakImplHelper5<
::my_module::XSomething, lang::XServiceInfo, lang::XInitialization, lang::XServiceName,
XAddIn>
{
OUString m_arg;
public:
// no need to implement XInterface, XTypeProvider, XWeak

// XInitialization will be called upon createInstanceWithArguments[AndContext]()
virtual void SAL_CALL initialize( Sequence< Any > const & args )
throw (Exception);
// XSomething
virtual OUString SAL_CALL methodOne( OUString const & str )
throw (RuntimeException);
virtual OUString SAL_CALL methodTwo( OUString const & str )
throw (RuntimeException);
virtual sal_Int32 SAL_CALL methodThree(const Sequence< Sequence< sal_Int32 > > &aValList )
throw (RuntimeException);
virtual Sequence< Sequence< sal_Int32 > > SAL_CALL methodFour(
const Sequence< Sequence< sal_Int32 > > &aValList )
throw (RuntimeException);

// XServiceName
virtual OUString SAL_CALL getServiceName() throw( uno::RuntimeException );
// XServiceInfo
virtual OUString SAL_CALL getImplementationName()
throw (RuntimeException);
virtual sal_Bool SAL_CALL supportsService( OUString const & serviceName )
throw (RuntimeException);
virtual Sequence< OUString > SAL_CALL getSupportedServiceNames()
throw (RuntimeException);
// XAddIn
virtual OUString SAL_CALL getProgrammaticFuntionName( const OUString& aDisplayName )
throw( uno::RuntimeException );
virtual OUString SAL_CALL getDisplayFunctionName( const OUString& aProgrammaticName )
throw( uno::RuntimeException );
virtual OUString SAL_CALL getFunctionDescription( const OUString& aProgrammaticName )
throw( uno::RuntimeException );
virtual OUString SAL_CALL getDisplayArgumentName(
const OUString& aProgrammaticName, sal_Int32 nArgument ) throw( uno::RuntimeException );
virtual OUString SAL_CALL getArgumentDescription(
const OUString& aProgrammaticName, sal_Int32 nArgument ) throw( uno::RuntimeException );
virtual OUString SAL_CALL getProgrammaticCategoryName(
const OUString& aProgrammaticName ) throw( uno::RuntimeException );
virtual OUString SAL_CALL getDisplayCategoryName(
const OUString& aProgrammaticName ) throw( uno::RuntimeException );
// XLocalizable
virtual void SAL_CALL setLocale( const lang::Locale& eLocale ) throw( uno::RuntimeException );
virtual lang::Locale SAL_CALL getLocale() throw( uno::RuntimeException );
};
</source>

The code is not complete with the four methods as you can see in the class declaration. Only your own XSomething interface is already implemented (see [[CompleteAddIn#Implementing_in_C.2B.2B_the_corresponding_four_Methods|above]]). You can wonder how is it possible to find all the methods in the class ? As you will learn below, the IDL files corresponding to interfaces have to be read for that. The number of interfaces you have to implement is dependant of your goal. If you want to create a component you have to implement XInterface interface and add more code, if you want to make a scriptable component you still add more code (and more interfaces : XTypeprovider, XServiceInfo and XWeak) and if you want to create an AddIn you have to add more (XAddin, XServiceName). This is explained in Developper's Guide. We first begin with a typical addin interface : XAddin.

==The XAddIn Interface==
Every add-in have to implement the <idl>com.sun.star.sheet.XAddIn</idl> interface. As usual what you have to do is described by an IDL file (or you can read the previous C++ class definition) :
<source lang="idl">
// IDL
module com { module sun { module star { module sheet {
interface XAddIn: com::sun::star::lang::XLocalizable
{
string getProgrammaticFuntionName( [in] string aDisplayName );
string getDisplayFunctionName( [in] string aProgrammaticName );
string getFunctionDescription( [in] string aProgrammaticName );
string getDisplayArgumentName(
[in] string aProgrammaticFunctionName,
[in] long nArgument );
string getArgumentDescription(
[in] string aProgrammaticFunctionName,
[in] long nArgument );
string getProgrammaticCategoryName( [in] string aProgrammaticFunctionName );
string getDisplayCategoryName( [in] string aProgrammaticFunctionName );
};
}; }; }; };
</source>
The corresponding C++ code is given now without explanation (for the moment)
<source lang="cpp">
// C++
// XAddIn
OUString SAL_CALL MyService2Impl::getProgrammaticFuntionName( const OUString& aDisplayName ) throw(
uno::RuntimeException )
{
// not used by calc
// (but should be implemented for other uses of the AddIn service)
return OUString();
}

OUString SAL_CALL MyService2Impl::getDisplayFunctionName( const OUString& aProgrammaticName ) throw(
uno::RuntimeException )
{ // a nested if implementation would be better
OUString aProgName, aRet;
aProgName = aProgrammaticName;
if (aProgName.equalsAscii("methodOne")) aRet = OUString::createFromAscii("method1");
if (aProgName.equalsAscii("methodTwo")) aRet = OUString::createFromAscii("method2");
if (aProgName.equalsAscii("methodThree")) aRet = OUString::createFromAscii("method3");
if (aProgName.equalsAscii("methodFour")) aRet = OUString::createFromAscii("method4");
return aRet;
}

OUString SAL_CALL MyService2Impl::getFunctionDescription( const OUString& aProgrammaticName ) throw(
uno::RuntimeException )
{ // a nested if implementation would be better
OUString aRet;
if (aProgrammaticName.equalsAscii("methodOne"))
aRet = OUString::createFromAscii("methodOne() : 1st try");
if (aProgrammaticName.equalsAscii("methodTwo"))
aRet = OUString::createFromAscii("methodTwo() : 1st try");
if (aProgrammaticName.equalsAscii("methodThree"))
aRet = OUString::createFromAscii("methodThree() : 1st try");
if (aProgrammaticName.equalsAscii("methodFour"))
aRet = OUString::createFromAscii("methodFour() : 1st try");
return aRet;
}

OUString SAL_CALL MyService2Impl::getDisplayArgumentName(
const OUString& aProgrammaticName, sal_Int32 nArgument ) throw( uno::RuntimeException )
{ // (requis) is added in French and probably (required) in English (see the snapshot below)
OUString aRet;
if (aProgrammaticName.equalsAscii("methodOne")||aProgrammaticName.equalsAscii("methodTwo"))
aRet = OUString::createFromAscii("a string");
if (aProgrammaticName.equalsAscii("methodThree")||aProgrammaticName.equalsAscii("methodFour"))
aRet = OUString::createFromAscii("a Cell Range");
return aRet;
}

OUString SAL_CALL MyService2Impl::getArgumentDescription(
const OUString& aProgrammaticName, sal_Int32 nArgument ) throw( uno::RuntimeException )
{
OUString aRet;
if (aProgrammaticName.equalsAscii("methodOne")||aProgrammaticName.equalsAscii("methodTwo"))
aRet = OUString::createFromAscii("method1/2:a string or a cell with a string is required");
if (aProgrammaticName.equalsAscii("methodThree")||aProgrammaticName.equalsAscii("methodFour"))
aRet = OUString::createFromAscii("method3/4:a cell range is required");
return aRet;
}

OUString SAL_CALL MyService2Impl::getProgrammaticCategoryName(const OUString& aProgrammaticName ) throw(
uno::RuntimeException )
{
OUString aRet( RTL_CONSTASCII_USTRINGPARAM("Add-In"));
return aRet;
}

OUString SAL_CALL MyService2Impl::getDisplayCategoryName(const OUString& aProgrammaticName ) throw(
uno::RuntimeException )
{
return getProgrammaticCategoryName( aProgrammaticName );
}
</source>

To understand what is this code related to, we provide a snapshot : read it carefully to see where the code works and provides the strings to print out in the autopilot frame :

[[Image:Addin2.png]]

I have used the method one as you can see above the autopilot frame, and I am ready to use the method two. What you can read in the autopilot comes directly from the C++ code except the French word "requis" which is probably translated by "required" in an English OpenOffice version.

== The XServiceName Interface==

Again the corresponding IDL file indicates what we have to do :
<source lang="idl">
// IDL
module com { module sun { module star { module lang {
interface XServiceName: com::sun::star::uno::XInterface
{
string getServiceName();
};
}; }; }; };
</source>
This interface is simple : one method :
<source lang="cpp">
//C++
// XServiceName
OUString SAL_CALL MyService2Impl::getServiceName() throw( uno::RuntimeException )
{
// name of specific AddIn service
return OUString::createFromAscii( "my_module.MyService2" );
}
</source>
See <idl>com.sun.star.lang.XServiceName</idl> for the complete documentation.

==The XServiceInfo Interface==
This <idl>com.sun.star.lang.XServiceInfo</idl> interface may be avoided. You have to implement it only if you want that your add-in is also scriptable : you can call it from OOoBasic for instance. It's time to present the corresponding IDL file :

<source lang="idl">
// IDL
module com { module sun { module star { module lang {
interface XServiceInfo: com::sun::star::uno::XInterface
{
string getImplementationName();
boolean supportsService( [in] string ServiceName );
sequence<string> getSupportedServiceNames();
};
}; }; }; };
</source>

Here is the corresponding C++ code :

<source lang="cpp">
// C++
// XServiceInfo implementation
OUString MyService2Impl::getImplementationName()
throw (RuntimeException)
{
// unique implementation name
return OUString( RTL_CONSTASCII_USTRINGPARAM("my_module.my_sc_impl.MyService2") );
}

sal_Bool MyService2Impl::supportsService( OUString const & serviceName )
throw (RuntimeException)
{
// this object only supports one service, so the test is simple
return serviceName.equalsAsciiL( RTL_CONSTASCII_STRINGPARAM("my_module.MyService2") ) ||
serviceName.equalsAsciiL( RTL_CONSTASCII_STRINGPARAM("com.sun.star.sheet.AddIn") );
}

Sequence< OUString > MyService2Impl::getSupportedServiceNames()
throw (RuntimeException)
{
return getSupportedServiceNames_MyService2Impl();
}

Reference< XInterface > SAL_CALL create_MyService2Impl(Reference< XComponentContext > const & xContext)
SAL_THROW( () )
{
return static_cast< lang::XTypeProvider * >( new MyService2Impl() );
}
</source>

==XInitialisation Interface==
This <idl>com.sun.star.lang.XInitialization</idl> interface could be removed without problem. I will remove it completely in the futur.
Here is the corresponding C++ code.
<source lang="cpp">
// C++
// XInitialization implemention
void MyService2Impl::initialize( Sequence< Any > const & args )
throw (Exception)
{
if (1 != args.getLength())
{
throw lang::IllegalArgumentException(
OUString( RTL_CONSTASCII_USTRINGPARAM("give a string instanciating this component!") ),
(::cppu::OWeakObject *)this, // resolve to XInterface reference
0 ); // argument pos
}
if (! (args[ 0 ] >>= m_arg))
{
throw lang::IllegalArgumentException(
OUString( RTL_CONSTASCII_USTRINGPARAM("no string given as argument!") ),
(::cppu::OWeakObject *)this, // resolve to XInterface reference
0 ); // argument pos
}
}
</source>

==XLocalizable Interface==

This <idl>com.sun.star.lang.XLocalizable</idl> interface is particular : we have let it in the class definition and give now the corresponding code but because the code do nothing, we don't add it as sixth interface when using the helper.

<source lang="cpp">
// C++
// XLocalizable
void SAL_CALL MyService2Impl::setLocale( const lang::Locale& eLocale ) throw( uno::RuntimeException )
{
// aFuncLoc = eLocale;
// InitData(); // change of locale invalidates resources!
}

lang::Locale SAL_CALL MyService2Impl::getLocale() throw( uno::RuntimeException )
{
// return aFuncLoc;
}
</source>

==Making a registerable component==
An add-in has to be registered. In fact if you want to use external code, you have to work with a registry. If you use your external code with OOoBasic you call it a component and if you use it with OOoCalc you call it an add-in. But both are very similar. In my knowledge the only exception to this registry rule is OOoBasic (under Windows) which can call directly an external DLL.

To supplement the above code we have to add :
<source lang="cpp">
// C++
/* shared lib exports implemented without helpers in service_impl1.cxx */
namespace my_sc_impl
{
static struct ::cppu::ImplementationEntry s_component_entries [] =
{
{
create_MyService2Impl, getImplementationName_MyService2Impl,
getSupportedServiceNames_MyService2Impl, ::cppu::createSingleComponentFactory,
0, 0
},
{ 0, 0, 0, 0, 0, 0 }
};
}

extern "C"
{
void SAL_CALL component_getImplementationEnvironment(
sal_Char const ** ppEnvTypeName, uno_Environment ** ppEnv )
{
*ppEnvTypeName = CPPU_CURRENT_LANGUAGE_BINDING_NAME;
}
sal_Bool SAL_CALL component_writeInfo(
lang::XMultiServiceFactory * xMgr, registry::XRegistryKey * xRegistry )
{
return ::cppu::component_writeInfoHelper(
xMgr, xRegistry, ::my_sc_impl::s_component_entries );
}
void * SAL_CALL component_getFactory(
sal_Char const * implName, lang::XMultiServiceFactory * xMgr,
registry::XRegistryKey * xRegistry )
{
return ::cppu::component_getFactoryHelper(
implName, xMgr, xRegistry, ::my_sc_impl::s_component_entries );
}
}
</source>

== The complete Code ==
It's time to give the C++ complete code :

<source lang="cpp">
//Listing 9 My first Add-In
//C++
#include <cppuhelper/implbase5.hxx> // "5" implementing five interfaces
#include <cppuhelper/factory.hxx>
#include <cppuhelper/implementationentry.hxx>

#include <com/sun/star/lang/XServiceInfo.hpp>
#include <com/sun/star/lang/XInitialization.hpp>
#include <com/sun/star/lang/XServiceName.hpp>
#include <com/sun/star/lang/IllegalArgumentException.hpp>
#include <com/sun/star/sheet/XAddIn.hpp>
#include <com/sun/star/lang/XLocalizable.hpp>
#include <my_module/XSomething.hpp>

using namespace ::rtl; // for OUString
using namespace ::com::sun::star; // for odk interfaces
using namespace ::com::sun::star::uno; // for basic types
using namespace ::com::sun::star::sheet;

namespace my_sc_impl
{

static Sequence< OUString > getSupportedServiceNames_MyService2Impl()
{
static Sequence < OUString > *pNames = 0;
if( ! pNames )
{
// MutexGuard guard( Mutex::getGlobalMutex() );
if( !pNames )
{
static Sequence< OUString > seqNames(2);
seqNames.getArray()[0] = OUString(RTL_CONSTASCII_USTRINGPARAM("my_module.MyService2"));
seqNames.getArray()[1] = OUString(RTL_CONSTASCII_USTRINGPARAM("com.sun.star.sheet.AddIn"));
pNames = &seqNames;
}
}
return *pNames;
}

static OUString getImplementationName_MyService2Impl()
{
static OUString *pImplName = 0;
if( ! pImplName )
{
// MutexGuard guard( Mutex::getGlobalMutex() );
if( ! pImplName )
{
static OUString implName( RTL_CONSTASCII_USTRINGPARAM("my_module.my_sc_implementation.MyService2") );
pImplName = &implName;
}
}
return *pImplName;
}

class MyService2Impl : public ::cppu::WeakImplHelper5<
::my_module::XSomething, lang::XServiceInfo, lang::XInitialization, lang::XServiceName,
/*lang::XLocalizable, */XAddIn>
{
OUString m_arg;
public:
// focus on three given interfaces,
// no need to implement XInterface, XTypeProvider, XWeak

// XInitialization will be called upon createInstanceWithArguments[AndContext]()
virtual void SAL_CALL initialize( Sequence< Any > const & args )
throw (Exception);
// XSomething
virtual OUString SAL_CALL methodOne( OUString const & str )
throw (RuntimeException);
// **********************ADDED
virtual OUString SAL_CALL methodTwo( OUString const & str )
throw (RuntimeException);
virtual sal_Int32 SAL_CALL methodThree(const Sequence< Sequence< sal_Int32 > > &aValList )
throw (RuntimeException);
virtual Sequence< Sequence< sal_Int32 > > SAL_CALL methodFour(
const Sequence< Sequence< sal_Int32 > > &aValList )
throw (RuntimeException);
// ********************** END ADDED
// XServiceName
virtual OUString SAL_CALL getServiceName() throw( uno::RuntimeException );
// XServiceInfo
virtual OUString SAL_CALL getImplementationName()
throw (RuntimeException);
virtual sal_Bool SAL_CALL supportsService( OUString const & serviceName )
throw (RuntimeException);
virtual Sequence< OUString > SAL_CALL getSupportedServiceNames()
throw (RuntimeException);
// XAddIn
virtual OUString SAL_CALL getProgrammaticFuntionName( const OUString& aDisplayName ) throw( uno::RuntimeException );
virtual OUString SAL_CALL getDisplayFunctionName( const OUString& aProgrammaticName ) throw( uno::RuntimeException );
virtual OUString SAL_CALL getFunctionDescription( const OUString& aProgrammaticName ) throw( uno::RuntimeException );
virtual OUString SAL_CALL getDisplayArgumentName(
const OUString& aProgrammaticName, sal_Int32 nArgument ) throw( uno::RuntimeException );
virtual OUString SAL_CALL getArgumentDescription(
const OUString& aProgrammaticName, sal_Int32 nArgument ) throw( uno::RuntimeException );
virtual OUString SAL_CALL getProgrammaticCategoryName(
const OUString& aProgrammaticName ) throw( uno::RuntimeException );
virtual OUString SAL_CALL getDisplayCategoryName(
const OUString& aProgrammaticName ) throw( uno::RuntimeException );
// XLocalizable
virtual void SAL_CALL MyService2Impl::setLocale( const lang::Locale& eLocale ) throw( uno::RuntimeException );
virtual lang::Locale SAL_CALL MyService2Impl::getLocale() throw( uno::RuntimeException );
};

// XInitialization implemention
void MyService2Impl::initialize( Sequence< Any > const & args )
throw (Exception)
{
if (1 != args.getLength())
{
throw lang::IllegalArgumentException(
OUString( RTL_CONSTASCII_USTRINGPARAM("give a string instanciating this component!") ),
(::cppu::OWeakObject *)this, // resolve to XInterface reference
0 ); // argument pos
}
if (! (args[ 0 ] >>= m_arg))
{
throw lang::IllegalArgumentException(
OUString( RTL_CONSTASCII_USTRINGPARAM("no string given as argument!") ),
(::cppu::OWeakObject *)this, // resolve to XInterface reference
0 ); // argument pos
}
}

// XServiceName
OUString SAL_CALL MyService2Impl::getServiceName() throw( uno::RuntimeException )
{
// name of specific AddIn service
return OUString::createFromAscii( "my_module.MyService2" );
}
// XSomething implementation
OUString MyService2Impl::methodOne( OUString const & str )
throw (RuntimeException)
{
return OUString( RTL_CONSTASCII_USTRINGPARAM(
"called methodOne() of MyService2 implementation: ") ) + m_arg + str;
}
// **********************ADDED

OUString MyService2Impl::methodTwo( OUString const & str )
throw (RuntimeException)
{
return OUString( RTL_CONSTASCII_USTRINGPARAM(
"called methodTwo() of MyService2 implementation: ") ) + m_arg + str;
}

sal_Int32 MyService2Impl::methodThree(const Sequence< Sequence< sal_Int32 > > &aValList )
throw (RuntimeException)
{ sal_Int32 n1, n2;
sal_Int32 nE1 = aValList.getLength();
sal_Int32 nE2;
sal_Int32 temp=0;
for( n1 = 0 ; n1 < nE1 ; n1++ )
{
const Sequence< sal_Int32 > rList = aValList[ n1 ];
nE2 = rList.getLength();
const sal_Int32* pList = rList.getConstArray();
for( n2 = 0 ; n2 < nE2 ; n2++ )
{
temp += pList[ n2 ];
}
}
return temp;
}

//It's a matrix operation should be called like : {=METHODFOUR(A1:B4)}
Sequence< Sequence< sal_Int32 > > MyService2Impl::methodFour(
const Sequence< Sequence< sal_Int32 > > &aValList )throw (RuntimeException)
{ sal_Int32 n1, n2;
sal_Int32 nE1 = aValList.getLength();
sal_Int32 nE2;
Sequence< Sequence< sal_Int32 > > temp = aValList;
for( n1 = 0 ; n1 < nE1 ; n1++ )
{
Sequence< sal_Int32 > rList = temp[ n1 ];
nE2 = rList.getLength();
for( n2 = 0 ; n2 < nE2 ; n2++ )
{
rList[ n2 ] += 4;
}
temp[n1]=rList;
}
return temp;
}

// ********************** END ADDED

// XAddIn

OUString SAL_CALL MyService2Impl::getProgrammaticFuntionName( const OUString& aDisplayName ) throw( uno::RuntimeException )
{
// not used by calc
// (but should be implemented for other uses of the AddIn service)
return OUString();
}

OUString SAL_CALL MyService2Impl::getDisplayFunctionName( const OUString& aProgrammaticName ) throw( uno::RuntimeException )
{
OUString aProgName, aRet;
aProgName = aProgrammaticName;
if (aProgName.equalsAscii("methodOne")) aRet = OUString::createFromAscii("method1");
if (aProgName.equalsAscii("methodTwo")) aRet = OUString::createFromAscii("method2");
if (aProgName.equalsAscii("methodThree")) aRet = OUString::createFromAscii("method3");
if (aProgName.equalsAscii("methodFour")) aRet = OUString::createFromAscii("method4");

return aRet;
}

OUString SAL_CALL MyService2Impl::getFunctionDescription( const OUString& aProgrammaticName ) throw( uno::RuntimeException )
{
OUString aRet;
if (aProgrammaticName.equalsAscii("methodOne"))
aRet = OUString::createFromAscii("methodOne() : 1st try");
if (aProgrammaticName.equalsAscii("methodTwo"))
aRet = OUString::createFromAscii("methodTwo() : 1st try");
if (aProgrammaticName.equalsAscii("methodThree"))
aRet = OUString::createFromAscii("methodThree() : 1st try");
return aRet;
}

OUString SAL_CALL MyService2Impl::getDisplayArgumentName(
const OUString& aProgrammaticName, sal_Int32 nArgument ) throw( uno::RuntimeException )
{
OUString aRet;
if (aProgrammaticName.equalsAscii("methodOne")||aProgrammaticName.equalsAscii("methodTwo"))
aRet = OUString::createFromAscii("a string");
if (aProgrammaticName.equalsAscii("methodThree")||aProgrammaticName.equalsAscii("methodFour"))
aRet = OUString::createFromAscii("a Cell Range");
return aRet;
}

OUString SAL_CALL MyService2Impl::getArgumentDescription(
const OUString& aProgrammaticName, sal_Int32 nArgument ) throw( uno::RuntimeException )
{
OUString aRet;
if (aProgrammaticName.equalsAscii("methodOne")||aProgrammaticName.equalsAscii("methodTwo"))
aRet = OUString::createFromAscii("method1/2:a string or a cell with a string is required");
if (aProgrammaticName.equalsAscii("methodThree")||aProgrammaticName.equalsAscii("methodFour"))
aRet = OUString::createFromAscii("method3/4:a cell range is required");
return aRet;
}

OUString SAL_CALL MyService2Impl::getProgrammaticCategoryName(
const OUString& aProgrammaticName ) throw( uno::RuntimeException )
{
OUString aRet( RTL_CONSTASCII_USTRINGPARAM("Add-In"));
return aRet;
}

OUString SAL_CALL MyService2Impl::getDisplayCategoryName(
const OUString& aProgrammaticName ) throw( uno::RuntimeException )
{
return getProgrammaticCategoryName( aProgrammaticName );
}

// XServiceInfo implementation
OUString MyService2Impl::getImplementationName()
throw (RuntimeException)
{
// unique implementation name
return OUString( RTL_CONSTASCII_USTRINGPARAM("my_module.my_sc_impl.MyService2") );
}
sal_Bool MyService2Impl::supportsService( OUString const & serviceName )
throw (RuntimeException)
{
// this object only supports one service, so the test is simple
// modified *********
return serviceName.equalsAsciiL( RTL_CONSTASCII_STRINGPARAM("my_module.MyService2") ) ||
serviceName.equalsAsciiL( RTL_CONSTASCII_STRINGPARAM("com.sun.star.sheet.AddIn") );
}
Sequence< OUString > MyService2Impl::getSupportedServiceNames()
throw (RuntimeException)
{
return getSupportedServiceNames_MyService2Impl();
}

Reference< XInterface > SAL_CALL create_MyService2Impl(
Reference< XComponentContext > const & xContext )
SAL_THROW( () )
{
return static_cast< lang::XTypeProvider * >( new MyService2Impl() );
}

// XLocalizable
void SAL_CALL MyService2Impl::setLocale( const lang::Locale& eLocale ) throw( uno::RuntimeException )
{
// aFuncLoc = eLocale;
// InitData(); // change of locale invalidates resources!
}

lang::Locale SAL_CALL MyService2Impl::getLocale() throw( uno::RuntimeException )
{
// return aFuncLoc;
}

}

/* shared lib exports implemented without helpers in service_impl1.cxx */
namespace my_sc_impl
{
static struct ::cppu::ImplementationEntry s_component_entries [] =
{
{
create_MyService2Impl, getImplementationName_MyService2Impl,
getSupportedServiceNames_MyService2Impl, ::cppu::createSingleComponentFactory,
0, 0
},
{ 0, 0, 0, 0, 0, 0 }
};
}

extern "C"
{
void SAL_CALL component_getImplementationEnvironment(
sal_Char const ** ppEnvTypeName, uno_Environment ** ppEnv )
{
*ppEnvTypeName = CPPU_CURRENT_LANGUAGE_BINDING_NAME;
}
sal_Bool SAL_CALL component_writeInfo(
lang::XMultiServiceFactory * xMgr, registry::XRegistryKey * xRegistry )
{
return ::cppu::component_writeInfoHelper(
xMgr, xRegistry, ::my_sc_impl::s_component_entries );
}
void * SAL_CALL component_getFactory(
sal_Char const * implName, lang::XMultiServiceFactory * xMgr,
registry::XRegistryKey * xRegistry )
{
return ::cppu::component_getFactoryHelper(
implName, xMgr, xRegistry, ::my_sc_impl::s_component_entries );
}
}
</source>
We have learnt now how things works and particularly how to manage sequence of sequence parameters or returned value.

{{Documentation/Note|This code is to set in <OpenOffice.org1.1_SDK>/examples/DevelopersGuide/Components/CppComponent path because there is no add-in exemple in the SDK. You have to slightly modify the corresponding makefile remove a source file to check this example.}}

=Utilities=
In order to provide utilities to interface OOo to other external libraries, we will provide in this section any utilities to transform classical variables into UNO variables.

==Transforming sequence of sequence into array==

If you plan to extend OOoCalc in any way, you will probably use an external library, for instance a C library like GSL. You will notice that the variables are in general arrays of double and not sequence.
Have a look to the case of Listing below where you see an imaginary method « foo ». The point is we use a sequence of sequence as parameter and we want to transform it into 2D array.
<source lang="cpp">
//C+
Sequence< Sequence< double > > MyService2Impl::foo(
const Sequence< Sequence< double > > &aValList )throw (RuntimeException)
{ sal_Int32 nE1 = aValList.getLength();
sal_Int32 nE2;

Sequence< double > rList = aValList[ 0 ];
nE2 = rList.getLength();
double table[nE1][nE2];
for( sal_Int32 n1 = 0 ; n1 < nE1; n1++ )
{
for (sal_Int32 n2=0;n2<nE2;n2++)
table[n1][n2]=aValList[n1][n2];
}
// we have a 2D array now
//!!!!!!!! This code is wrong : double table[nE1][nE2]; with nE1 and nE2
//!!!!!!!! unknown at the compilation time. !!!!!!!!
// I have used this code with success but I don't know why ?
// Perhaps the compiler use a constructor in this case ?
// I will have a look as sooner as possible
</source>
At the end of this program we have a 2D array named « table » and we show how to construct it. (I have tried a way using getArray() but without success).

As mentioned in the comments, this code has a poor quality in my knowledge. At the moment, I provide other code [[SDKCppLanguage#More_Abstractions_with_STL|here]]

==Transforming an Array into Sequence of Sequence==

Imagine your calculus provides a 1D array named « z » and you want to construct a sequence of sequence before returning it. Here is what you could do :
<source lang="cpp">
//C+
...
// here a line is constructed with size (nE2-1)*2
Sequence< double > solList1D(z,(nE2-1)*2);
Sequence< Sequence< double > > solList2D(1);
solList2D[0]=solList1D;
return solList2D;
</source>

A similar problem encountered later has to be solved differently : I start from an 1D array but this array contains, real part and imaginary part « The n-1 roots are returned in the packed complex array z of length 2(n-1), alternating real and imaginary parts » I want to show the result in Calc but with two rows (real part and imaginary part) with as many lines as necessary. Here is the way :

<source lang="cpp">
//C+
...
// two rows and nE2-1 lines starting from an array "z" with (nE2-1)*2 lements
Sequence< double > solList1D(2);
Sequence< Sequence< double > > solList2D(nE2-1);
for( int j=0;j<((nE2-1)<<1);j+=2){ // (nE2-1)<<1 is faster than (nE2-1)*2
for( int i=0; i<2 ; i++){
solList1D[i]=z[i+j];
}
solList2D[j>>1]=solList1D;//j >> 2 is faster than j/2
}
return solList2D;
</source>

Sometimes we have to use Standard Template Library because the library we want to interface is in C++. Eric Ehlers has interfaced a C++ library (QuantLib project) and then provide any interesting code [http://www.quantlibaddin.org here]. See particularly the file calcutils.cpp. I have reproduct part of the code [[SDKCppLanguage#More_Abstractions_with_STL|here]] but with using template.

=Interfacing the GSL (GNU Scientific Library)=

Our goal is now to provide an example of intarfacing OOo with a scientific library. To give the possibility of accessing all the library is an enormous task that I cannot realize. I only want to show the way.

==First step==

The first step is to install the GSL. See the GSL documentation

==Second step==

Find what gsl function do you want to wrapp and write the corresponding IDL file. For this example I am interested in finding the complex roots of a polynom. The corresponding function is « gsl_poly_complex_solve ».

The corresponding IDL file is (keeping all the old methods of the previous sections) :

<source lang="idl">
//Listing 14.14 My SDL interfacing Add-In : the IDL File
// IDL
module my_module
{
interface XSomething : com::sun::star::uno::XInterface
{
string methodOne( [in] string val );
string methodTwo( [in] string val );
long methodThree( [in] sequence< sequence< long > > aValList );
sequence< sequence< long > > methodFour( [in] sequence< sequence< long > > aValList );
sequence< sequence< double > > poly_complex_solve([in] sequence< sequence< double > > aValList );
};
service MyService2
{
interface XSomething;
interface com::sun::star::lang::XInitialization;
interface com::sun::star::lang::XServiceName;
interface com::sun::star::sheet::XAddIn;
};
};
</source>

The name of the new method will be « poly_complex_solve »

==Third Step==

You have to modify the makefile to link your addin with the GSL libraries :
<pre>
#Listing 14.15 New MakeFile
....
ifeq "$(OS)" "WIN"
$(SHAREDLIB_OUT)/%.$(SHAREDLIB_EXT) : $(SLOFILES) $(OUT_COMP_GEN)/%.def
-$(MKDIR) $(subst /,$(PS),$(@D))
$(LINK) $(LIBRARY_LINK_FLAGS) /OUT:$@ /MAP:$(OUT_COMP_GEN)/$(subst $(SHAREDLIB_EXT),map,$(@F)) \
/DEF:$(OUT_COMP_GEN)/$(subst $(SHAREDLIB_EXT),def,$(@F)) $(SLOFILES) \
$(CPPUHELPERLIB) $(CPPULIB) $(SALLIB) $(STLPORTLIB) msvcrt.lib kernel32.lib
else
$(SHAREDLIB_OUT)/%.$(SHAREDLIB_EXT) : $(SLOFILES)
-$(MKDIR) $(subst /,$(PS),$(@D))
$(LINK) $(LIBRARY_LINK_FLAGS) $(LINK_LIBS) -o $@ $^\
$(CPPUHELPERLIB) $(CPPULIB) $(SALLIB) $(STLPORTLIB) $(STC++LIB) -lgsl -lgslcblas -lm
# $(CPPUHELPERLIB)
endif
....
</pre>

==Step Four==

Write the code and compile. The code given below only works when the polynomial coefficients are given in a line. In all the other cases it returns the same values as given in entry.
<source lang="cpp">
//Listing 14.16 New Code
// C++
....
#include <gsl/gsl_poly.h>
....
Sequence< Sequence< double > > MyService2Impl::poly_complex_solve(
const Sequence< Sequence< double > > &aValList )throw (RuntimeException)
{
sal_Int32 nE1 = aValList.getLength();
sal_Int32 nE2;
Sequence< double > rList = aValList[ 0 ];
nE2 = rList.getLength();
double table[nE1][nE2];
for( sal_Int32 n1 = 0 ; n1 < nE1; n1++ )
{
for (sal_Int32 n2=0;n2<nE2;n2++)
table[n1][n2]=aValList[n1][n2];
}
// I have a 2D nE1xnE2 table here
if (nE1==1){ // real coefficients horizontally disposed
double z[(nE2-1)*2];
gsl_poly_complex_workspace * w = gsl_poly_complex_workspace_alloc(nE2);
gsl_poly_complex_solve(table[0],nE2,w,z);
gsl_poly_complex_workspace_free(w);
Sequence< double > solList1D(2);
Sequence< Sequence< double > > solList2D(nE2-1);
for( int j=0;j<((nE2-1)<<1);j+=2){
for( int i=0; i<2 ; i++){
solList1D[i]=z[i+j];
}
solList2D[j>>1]=solList1D;
}
return solList2D;
} else
if (nE2==1){ // real coefficients vertically disposed : doesn't work at the moment
Sequence< Sequence< double > > temp = aValList; // return the coefficients
return temp;
} else {
// If here : error
Sequence< Sequence< double > > temp = aValList; // return the coefficients
return temp;
}
}
</source>
Here is the result :
; Résults
{| border cellspacing="0" width="550"
|- style = "background:#b3e2d1;text-align:center"
| |x°||x¹||x²||x³||x^4||x^5
|- style="text-align:center"
| -1||0||0||0||0||1
|- style="text-align:center"
| || || || || ||
|- style="text-align:center"
| ||-0.81||0.59 || || ||
|- style="text-align:center"
| ||-0.81||-0.59|| || ||
|- style="text-align:center"
| ||0.31||0.95|| || ||
|- style="text-align:center"
| ||0.31||-0.95|| || ||
|- style="text-align:center"
| ||1||0|| || ||
|}

where you see horizontally the polynomial coefficients and vertically the five roots with real part (left) and imaginary part (right).
=Notes=
{{Documentation/Caution|If you are installing an external addin under linux and encounter a problem verify the dynamic library dependance with ldd command : <code>ldd your_addin.so</code> to see if a dynamic library fails.}}
{{Documentation/Note|Instead of going further with interfacing the GSL, bear in mind there is an advanced project of interfacing the giac library (giac is a Computer Algebra System used in [http://www-fourier.ujf-grenoble.fr/~parisse/giac/doc/en/casref_en/casref_en.html XCas]) which is already working. Here is the [http://cdeval.free.fr/spip.php?article132 French Documentation] of the corresponding addin. You can download [http://cdeval.free.fr/CmathOOoUpdate/CmathOOoCAS.oxt the version 1.0] for Linux or M$ Windows (same file for both version).}}

=Home Page=
[[Image:HomePageCpp.png]] [[Using_Cpp_with_the_OOo_SDK|Return to Document Home page]]

=See also=

'''This article is under construction''' and if you want to go further, for the moment have a look to the following references :
* [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno|C++ and UNO tutorial]]
*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [[Extensions_Packager|Extensions Packager]] (BasicAddonBuilder from [mailto:paolomantovani@openoffice.org Paolo Mantovani])
* [[Calc/Add-In/Project_Type|Java Calc Add-in]]
* [[API/Samples/Java/CalcAddin|An other Java Calc Add-in example]]
* [http://www.oooforum.org/forum/viewtopic.phtml?t=29552 Add-In in C++]
* [http://sc.openoffice.org/addin_howto.html How to add-in in OpenOffice.org Calc]
* [http://api.openoffice.org/docs/common/ref/com/sun/star/sheet/AddIn.html Service AddIn Documentation]
* [http://perso.wanadoo.fr/moutou/MyUNODoc_HTML/UNOCppAPI13.html Constructing Components]
* 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
* [[SDKInstallation | How to install the SDK and compile the C++ examples]]
* [[SDKCppLanguage | The UNO C++ Language]]
* QuantLibAddin exports the functionality of the QuantLib analytics library as Addins on a variety of platforms including OpenOffice.org Calc and can be found here : http://quantlib.org/quantlibaddin/

[[Category:Calc|Add-Ins 10 Complete]]
[[Category:API|Calc]]
[[Category:Add-In|Calc]]
[[Category:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

Documentation/DevGuide/Database/Scrollable Result Sets

2010-02-05T03:33:19Z

Newacct:

{{Documentation/DevGuide/DatabaseTOC
|Database2c=block
|DatabaseResult=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Database/Using the getXXX Methods
|NextPage=Documentation/DevGuide/Database/Modifiable Result Sets
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Database/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Scrollable Result Sets}}

The interface <idl>com.sun.star.sdbc.XResultSet</idl> offers methods to move the cursor back and forth to an arbitrary row, and get the current position of the cursor. Scrollable result sets are necessary to create GUI tools that can browse result sets. It also may be required to move a specific row to work with it. Before taking advantage of these features, create a scrollable <code>ResultSet</code> object. The following lines of code illustrate one way to create a scrollable <code>ResultSet</code> object:
<source lang="java">
XStatement xStatement = xConnection.createStatement();
XPropertySet xProp = (XPropertySet)UnoRuntime.queryInterface(XPropertySet.class, xStatement);

xProp.setPropertyValue("ResultSetType",new java.lang.Integer(ResultSetType.SCROLL_INSENSITIVE));
xProp.setPropertyValue("ResultSetConcurrency", new java.lang.Integer(ResultSetConcurrency.UPDATABLE));

XResultSet xResult = xStatement.executeQuery("SELECT FIRSTNAME, LASTNAME FROM SALES");
</source>
This code is similar to what was used earlier, except that it sets two property values at the <code>Statementobject</code>. These properties have to be set before the statement is executed.

The value of the property <code>ResultSetType</code> must be one of three constants defined in <idl>com.sun.star.sdbc.ResultSetType</idl>: <code>FORWARD_ONLY</code>, <code>SCROLL_INSENSITIVE</code> and <code>SCROLL_SENSITIVE</code>.

The property <code>ResultSetConcurrency</code> must be one out of the two <idl>com.sun.star.sdbc.ResultSetConcurrency</idl> constants <code>READ_ONLY</code> and <code>UPDATABLE</code>. When a <code>ResultSetType</code> is specified, it must be specified if it is read-only or modifiable.

If any constants for the type and modifiability of a <code>ResultSet</code> object are not specified, <code>FORWARD_ONLY</code> and <code>READ_ONLY</code> will automatically be created.

Specifying the constant <code>FORWARD_ONLY</code> creates a non-scrollable result set, that is, the cursor moves forward only. A scrollable <code>ResultSet</code> is obtained by specifying <code>SCROLL_INSENSITIVE</code> or <code>SCROLL_SENSITIVE</code>. Sensitive or insensitive refers to changes made to the underlying data after the result set has been opened. A <code>SCROLL_INSENSITIVE</code> result set does not reflect changes to the underlying data, while a <code>SCROLL_SENSITIVE</code> result set shows changes. However, not all drivers and databases support change sensitivity.

In scrollable result sets, the counterpart to <code>next()</code> is the method <code>previous()</code>, which moves the cursor backward. Both methods return false when the cursor goes to the position after the last row or before the first row. This allows them to be used in a while loop.

The following two examples show the usage of <code>next()</code> and <code>previous()</code> together with while:

<source lang="java">
XStatement stmt = con.createStatement();

XPropertySet xProp = (XPropertySet)UnoRuntime.queryInterface(XPropertySet.class, stmt);
xProp.setPropertyValue("ResultSetType",new java.lang.Integer(ResultSetType.SCROLL_INSENSITIVE));
xProp.setPropertyValue("ResultSetConcurrency", new java.lang.Integer(ResultSetConcurrency.READ_ONLY));

XResultSet srs = stmt.executeQuery("SELECT NAME, PRICE FROM SALES");

XRow row = (XRow)UnoRuntime.queryInterface(XRow.class, srs);

while (srs.next()) {
String name = row.getString(1);
float price = row.getFloat(2);
System.out.println(name + " " + price);
}
</source>
The printout will look similar to this:

Linux 32
Beef 15.78
Orange juice 1.50

To process the rows going backward, the cursor must start out after the last row. The cursor is moved to the position after the last row with the method <code>afterLast()</code>. Then <code>previous()</code> moves the cursor from the position after the last row to the last row, and then up to the first row with each iteration through the while loop. The loop ends when the cursor reaches the position before the first row, where <code>previous()</code> returns false.

<source lang="java">
XStatement stmt = con.createStatement();

XPropertySet xProp = (XPropertySet)UnoRuntime.queryInterface(XPropertySet.class,stmt);
xProp.setPropertyValue("ResultSetType", new java.lang.Integer(ResultSetType.SCROLL_INSENSITIVE));
xProp.setPropertyValue("ResultSetConcurrency", new java.lang.Integer(ResultSetConcurrency.READ_ONLY));

XResultSet srs = stmt.executeQuery("SELECT NAME, PRICE FROM SALES");

XRow row = (XRow)UnoRuntime.queryInterface(XRow.class, srs);

srs.afterLast();
while (srs.previous()) {
String name = row.getString(1);
float price = row.getFloat(2);
System.out.println(name + " " + price);
}
</source>
The printout will look similar to this:

Orange juice 1.50
Beef 15.78
Linux 32

The column values are the same, but the rows are in the reverse order.

The cursor can be moved to a specific row in a ResultSet object. The methods <code>first()</code>, <code>last()</code>, <code>beforeFirst()</code>, and <code>afterLast()</code> move the cursor to the row indicated by the method names.

The method <code>absolute()</code> moves the cursor to the row number indicated in the argument passed. If the number is positive, the cursor moves the given number from the beginning. Calling <code>absolute(1)</code> moves the cursor to the first row. If the number is negative, the cursor moves the given number of rows from the end. Calling <code>absolute(-1)</code> sets the cursor to the last row. The following line of code moves the cursor to the fourth row of srs:
<source lang="java">
srs.absolute(4);
</source>
If srs has 500 rows, the following line of code moves the cursor to row 497:
<source lang="java">
srs.absolute(-4);
</source>
The method <code>relative()</code> moves the cursor by an arbitrary number of rows from the current row. A positive number moves the cursor forward, and a negative number moves the cursor backwards. For example, in the following code fragment, the cursor moves to the fourth row, then to the first row, and finally to the third row:
<source lang="java">
srs.absolute(4); // cursor is on the fourth row
...
srs.relative(-3); // cursor is on the first row
...
srs.relative(2); // cursor is on the third row
</source>
The method <code>getRow()</code> returns the number of the current row. For example, use <code>getRow()</code> to verify the current position of the cursor in the previous example using the following code:
<source lang="java">
srs.absolute(4);
int rowNum = srs.getRow(); // rowNum should be 4
srs.relative(-3);
rowNum = srs.getRow(); // rowNum should be 1
srs.relative(2);
rowNum = srs.getRow(); // rowNum should be 3
</source>
Note that some drivers do not support the getRow method. They always return 0.

There are four methods to verify if the cursor is at a particular position. The position is stated in their names: <code>isFirst()</code>, <code>isLast()</code>, <code>isBeforeFirst()</code>, and <code>isAfterLast()</code>. These methods return a boolean that can be used in a conditional statement. For example, the following code fragment tests if the cursor is after the last row before invoking the method <code>previous()</code> in a while loop. If the method <code>isAfterLast()</code> returns false, the cursor is not after the last row, so the method afterLast can be invoked. This guarantees that the cursor is after the last row and that using the method <code>previous()</code> in the while loop stop at every row in srs.
<source lang="java">
if (!srs.isAfterLast()) {
srs.afterLast();
}
while (srs.previous()) {
String name = row.getString(1);
float price = row.getFloat(2);
System.out.println(name + " " + price);
}
</source>
How to use the two methods from the <code>XResultSetUpdate</code> interface to move the cursor: <code>moveToInsertRow()</code> and <code>moveToCurrentRow()</code> are discussed in the next section. There are examples illustrating why moving the cursor to certain positions may be required.

{{PDL1}}

[[Category:Documentation/Developer's Guide/Database Access]]

Documentation/DevGuide/OfficeDev/Using the Desktop

2010-02-05T03:23:48Z

Newacct:

{{Documentation/DevGuide/OfficeDevTOC
|OfficeDev2a=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/OfficeDev/Dispatch Framework
|NextPage=Documentation/DevGuide/OfficeDev/Using the Component Framework
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/OfficeDev/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Using the Desktop}}

[[Image:framework.png|none|thumb|450px|Desktop Service and Component Framework]]


The <idl>com.sun.star.frame.Desktop</idl> service available at the global service manager includes the service <idl>com.sun.star.frame.Frame</idl>. The Desktop service specification provides three interfaces: <idl>com.sun.star.frame.XDesktop</idl>, <idl>com.sun.star.frame.XComponentLoader</idl> and <idl>com.sun.star.document.XEventBroadcaster</idl>, as shown in the following UML chart:

[[Image:Desktop.png|none|thumb|450px|UML description of the desktop service]]

The interface <idl>com.sun.star.frame.XDesktop</idl> provides access to frames and components, and controls the termination of the office process. It defines the following methods:
<source lang="idl">
com::sun::star::frame::XFrame getCurrentFrame ()
com::sun::star::container::XEnumerationAccess getComponents ()
com::sun::star::lang::XComponent getCurrentComponent ()
boolean terminate ()
void addTerminateListener ( [in] com::sun::star::frame::XTerminateListener xListener)
void removeTerminateListener ( [in] com::sun::star::frame::XTerminateListener xListener)
</source>
The methods <code>getCurrentFrame()</code> and <code>getCurrentComponent()</code> distribute the active frame and document model, whereas <code>getComponents()</code> returns a <idl>com.sun.star.container.XEnumerationAccess</idl> to all loaded documents. For documents loaded in the desktop environment the methods <code>getComponents()</code> and <code>getCurrentComponent()</code> always return the <idl>com.sun.star.lang.XComponent</idl> interface of the document model.

{{Documentation/Tip|If a specific document component is required, but you are not sure whether this component is the current component, use <tt>getComponents()</tt> to get an enumeration of all document components, check each for the existence of the <idl>com.sun.star.frame.XModel</idl> interface and use <tt>getURL()</tt> at <tt>XModel</tt> to identify your document. Since not all components have to support <tt>XModel</tt>, test for <tt>XModel</tt> before calling <tt>getURL()</tt>.}}

The office process is usually terminated when the user selects '''File - Exit''' or after the last application window has been closed. Clients can terminate the office through a call to <code>terminate()</code> and add a terminate listener to veto the shutdown process.


As long as the Windows quickstarter is active, the soffice executable is not terminated.

The following sample shows an <idl>com.sun.star.frame.XTerminateListener</idl> implementation that prevents the office from being terminated when the class <code>TerminationTest</code> is still active:
<source lang="java">
import com.sun.star.frame.TerminationVetoException;
import com.sun.star.frame.XTerminateListener;

public class TerminateListener implements XTerminateListener {

public void notifyTermination (com.sun.star.lang.EventObject eventObject) {
System.out.println("about to terminate...");
}

public void queryTermination (com.sun.star.lang.EventObject eventObject)
throws TerminationVetoException {

// test if we can terminate now
if (TerminationTest.isAtWork()) {
System.out.println("Terminate while we are at work? No way!");
throw new TerminationVetoException() ; // this will veto the termination,
// a call to terminate() returns false
}
}

public void disposing (com.sun.star.lang.EventObject eventObject) {
}
}
</source>
The following class <code>TerminationTest</code> tests the <code>TerminateListener</code> above.
<source lang="java">
import com.sun.star.bridge.XUnoUrlResolver;
import com.sun.star.uno.UnoRuntime;
import com.sun.star.uno.XComponentContext;
import com.sun.star.lang.XMultiComponentFactory;
import com.sun.star.beans.XPropertySet;
import com.sun.star.beans.PropertyValue;

import com.sun.star.frame.XDesktop;
import com.sun.star.frame.TerminationVetoException;
import com.sun.star.frame.XTerminateListener;

public class TerminationTest extends java.lang.Object {

private static boolean atWork = false;

public static void main(String[] args) {

XComponentContext xRemoteContext = null;
XMultiComponentFactory xRemoteServiceManager = null;
XDesktop xDesktop = null;

try {
// connect and retrieve a remote service manager and component context
XComponentContext xLocalContext =
com.sun.star.comp.helper.Bootstrap.createInitialComponentContext(null);
XMultiComponentFactory xLocalServiceManager = xLocalContext.getServiceManager();
Object urlResolver = xLocalServiceManager.createInstanceWithContext(
"com.sun.star.bridge.UnoUrlResolver", xLocalContext );
XUnoUrlResolver xUnoUrlResolver = (XUnoUrlResolver) UnoRuntime.queryInterface(
XUnoUrlResolver.class, urlResolver );
Object initialObject = xUnoUrlResolver.resolve(
"uno:socket,host=localhost,port=2083;urp;StarOffice.ServiceManager" );
XPropertySet xPropertySet = (XPropertySet)UnoRuntime.queryInterface(
XPropertySet.class, initialObject);
Object context = xPropertySet.getPropertyValue("DefaultContext");
xRemoteContext = (XComponentContext)UnoRuntime.queryInterface(
XComponentContext.class, context);
xRemoteServiceManager = xRemoteContext.getServiceManager();

// get Desktop instance
Object desktop = xRemoteServiceManager.createInstanceWithContext (
"com.sun.star.frame.Desktop", xRemoteContext);
xDesktop = (XDesktop)UnoRuntime.queryInterface(XDesktop.class, desktop);

TerminateListener terminateListener = new TerminateListener ();
xDesktop.addTerminateListener (terminateListener);

// try to terminate while we are at work
atWork = true;
boolean terminated = xDesktop.terminate ();
System.out.println("The Office " +
(terminated ? "has been terminated" : "is still running, we are at work"));

// no longer at work
atWork = false;
// once more: try to terminate
terminated = xDesktop.terminate ();
System.out.println("The Office " +
(terminated ? "has been terminated" :
"is still running. Someone else prevents termination, e.g. the quickstarter"));
}
catch (java.lang.Exception e){
e.printStackTrace();
}
finally {
System.exit(0);
}

}
public static boolean isAtWork() {
return atWork;
}

}
</source>

The office freezes when <code>terminate()</code> is called if there are unsaved changes. As a workaround set all documents into an unmodified state through their <idl>com.sun.star.util.XModifiable</idl> interface or store them using <idl>com.sun.star.frame.XStorable</idl>.

The Desktop offers a facility to load components through its interface <idl>com.sun.star.frame.XComponentLoader</idl>. It has one method:
<source lang="idl">
com::sun::star::lang::XComponent loadComponentFromURL ( [in] string aURL,
[in] string aTargetFrameName,
[in] long nSearchFlags,
[in] sequence < com::sun::star::beans::PropertyValue aArgs > )
</source>
Refer to chapter [[Documentation/DevGuide/OfficeDev/Handling Documents|Handling Documents]] for details about the loading process.

For versions beyond 641, the desktop also provides an interface that allows listeners to be notified about certain document events through its interface <idl>com.sun.star.document.XEventBroadcaster</idl>.
<source lang="idl">
void addEventListener ( [in] com::sun::star::document::XEventListener xListener)
void removeEventListener ( [in] com::sun::star::document::XEventListener xListener)
</source>
The <code>XEventListener</code> must implement a single method (besides <code>disposing()</code>):
<source lang="idl">
[oneway] void notifyEvent ( [in] com::sun::star::document::EventObject Event )
</source>
The struct <idl>com.sun.star.document.EventObject</idl> has a <code>string</code> member <code>EventName</code> that assumes one of the values specified in <idl>com.sun.star.document.Events</idl>. The corresponding events are found on the Events tab of the '''Tools - Configure''' dialog when the option {{PRODUCTNAME}} is selected.

The desktop broadcasts these events for all loaded documents.

The current version of {{PRODUCTNAME}} does not have a GUI element as a desktop. The redesign of the {{PRODUCTNAME}} GUI in StarOffice 5.x and later resulted in the <idl>com.sun.star.frame.Frame</idl> service part of the desktop service is now non-functional. While the <code>XFrame</code> interface can still be queried from the desktop, almost all of its methods are dummy implementations. The default implementation of the desktop object in {{PRODUCTNAME}} is not able to contain a component and refuses to be attached to it, because the desktop is still a frame that is the root for the common hierarchy of all frames in {{PRODUCTNAME}}. The desktop has to be a frame because its <idl>com.sun.star.frame.XFramesSupplier</idl> interface must be passed to [http://api.openoffice.org/docs/common/ref/com/sun/star/frame/XFrame.html#setCreator com.sun.star.frame.XFrame:setCreator]() at the child frames, therefore the desktop becomes the parent frame. However, the following functionality of <idl>com.sun.star.frame.Frame</idl> is still in place:

The desktop interface <idl>com.sun.star.frame.XFramesSupplier</idl> offers methods to access frames. This interface inherits from <idl>com.sun.star.frame.XFrame</idl>, and introduces the following methods:
<source lang="idl">
com::sun::star::frame::XFrames getFrames ()
com::sun::star::frame::XFrame getActiveFrame ()
void setActiveFrame ( [in] com::sun::star::frame::XFrame xFrame)
</source>
The method <code>getFrames()</code> returns a <idl>com.sun.star.frame.XFrames</idl> container, that is a <idl>com.sun.star.container.XIndexAccess</idl>, with additional methods to add and remove frames:
<source lang="idl">
void append ( [in] com::sun::star::frame::XFrame xFrame )
sequence < com::sun::star::frame::XFrame > queryFrames ( [in] long nSearchFlags )
void remove ( [in] com::sun::star::frame::XFrame xFrame )
</source>
This <code>XFrames</code> collection is used when frames are added to the desktop to become application windows.

Through <code>getActiveFrame()</code>, you access the active sub-frame of the desktop frame, whereas <code>setActiveFrame()</code> is called by a sub-frame to inform the desktop about the active sub-frame.


The object returned by <code>getFrames()</code> does not support <code>XTypeProvider</code>, therefore it cannot be used with {{PRODUCTNAME}} Basic.

The parent interface of <code>XFramesSupplier</code>, <idl>com.sun.star.frame.XFrame</idl> is functional by accessing the frame hierarchy below the desktop. These methods are discussed in the section [[Documentation/DevGuide/OfficeDev/Frames|Frames]] below:
<source lang="idl">
com::sun::star::frame::XFrame findFrame ( [in] string aTargetFrameName, [in] long nSearchFlags );
boolean isTop ();
</source>
The generic dispatch interface <idl>com.sun.star.frame.XDispatchProvider</idl> executes functions of the internal <code>Desktop</code> implementation that are not accessible through specialized interfaces. Dispatch functions are described by a command URL. The <code>XDispatchProvider</code> returns a dispatch object that dispatches a given command URL. A reference of command URLs supported by the desktop is available on OpenOffice ([http://www.openoffice.org/files/documents/25/60/commands_11beta.html http://www.openoffice.org/files/documents/25/60/commands_11beta.html]). Through the <idl>com.sun.star.frame.XDispatchProviderInterception</idl>, client code intercepts the command dispatches at the desktop. The dispatching process is described in section [[Documentation/DevGuide/OfficeDev/Using the Dispatch Framework|Using the Dispatch Framework]].

{{PDL1}}

[[Category:Documentation/Developer's Guide/Office Development]]

Documentation/DevGuide/Drawings/Transforming

2010-01-29T08:57:14Z

Newacct:

{{Documentation/DevGuide/DrawingsTOC
|Drawing2c=block
|DrawingShapes=block
|DrawingOp=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Drawings/Rotating and Shearing
|NextPage=Documentation/DevGuide/Drawings/Ordering
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Drawings/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Transforming}}
Changing the size, rotation and shearing of an object can be done by using the transformation mechanism provided by {{PRODUCTNAME}}. The matrix of our API is a standard homogenous 3x3 matrix that may be used together with the java.awt.geom.AffineTransform class from Java. The transformation received describes the actual values of the transformations as a linear combination of the single matrices. The basic object without transformation has a size of (1, 1) and a position of (0, 0), and is not rotated or sheared. Thus, to transform an object get its matrix and multiply from the left side to influence the current appearance. To set the whole transformation directly, build a combined matrix of the single values mentioned above and apply it to the object.


XPropertySet xPropSet = (XPropertySet)UnoRuntime.queryInterface( XPropertySet.class, xShape );
// take the current tranformation matrix
HomogenMatrix3 aHomogenMatrix3 = (HomogenMatrix3)xPropSet.getPropertyValue("Transformation");
java.awt.geom.AffineTransform aOriginalMatrix = new java.awt.geom.AffineTransform(aHomogenMatrix3.Line1.Column1, aHomogenMatrix3.Line2.Column1,
aHomogenMatrix3.Line1.Column2, aHomogenMatrix3.Line2.Column2,
aHomogenMatrix3.Line1.Column3, aHomogenMatrix3.Line2.Column3 );
// rotate the object by 15 degrees
AffineTransform aNewMatrix1 = new AffineTransform();
aNewMatrix1.setToRotation(Math.toRadians(15));
aNewMatrix1.concatenate(aOriginalMatrix);
// and translate the object by 2cm on the x-axis
AffineTransform aNewMatrix2 = new AffineTransform();
aNewMatrix2.setToTranslation(2000, 0);
aNewMatrix2.concatenate(aNewMatrix1);
double aFlatMatrix[] = new double[6];aNewMatrix2.getMatrix(aFlatMatrix);
// convert the flatMatrix to our HomogenMatrix3 structure
aHomogenMatrix3.Line1.Column1 = aFlatMatrix[0];
aHomogenMatrix3.Line2.Column1 = aFlatMatrix[1];
aHomogenMatrix3.Line1.Column2 = aFlatMatrix[2];
aHomogenMatrix3.Line2.Column2 = aFlatMatrix[3];
aHomogenMatrix3.Line1.Column3 = aFlatMatrix[4];
aHomogenMatrix3.Line2.Column3 = aFlatMatrix[5];
xPropSet.setPropertyValue("Transformation", aHomogenMatrix3);

{{PDL1}}

[[Category:Documentation/Developer's Guide/Drawing Documents and Presentation Documents]]

Documentation/DevGuide/Charts/3-D Charts

2010-01-29T06:00:29Z

Newacct:

{{Documentation/DevGuide/ChartsTOC
|Charts2b=block
|ChartsParts=block
|ChartsFeat=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Charts/Statistics
|NextPage=Documentation/DevGuide/Charts/Pie Charts
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Charts/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:3-D Charts}}

Some chart types can display a 3-dimensional representation. To switch a chart to 3-dimensional, set the boolean property <code>Dim3D</code> of the service <idl>com.sun.star.chart.Dim3DDiagram</idl>.

In addition to this property, bar charts support a property called <code>Deep</code> (see service <idl>com.sun.star.chart.BarDiagram</idl>) that arranges the series of a bar chart along the z-axis, which in a chart, points away from the spectator. The service <idl>com.sun.star.chart.Chart3DBarProperties</idl> offers a property <code>SolidType</code> to set the style of the data point solids. The solid styles can be selected from cuboids, cylinders, cones, and pyramids with a square base (see constants in <idl>com.sun.star.chart.ChartSolidType</idl>).

The <code>XDiagram</code> of a 3-dimensional chart is also a scene object that supports modification of the rotation and light sources. The example below shows how to rotate the scene object and add another light source.
<source lang="java">
// prerequisite: maDiagram contains a valid bar diagram
// ...

import com.sun.star.drawing.HomogenMatrix;
import com.sun.star.drawing.HomogenMatrixLine;
import com.sun.star.chart.X3DDisplay;
import com.sun.star.beans.XPropertySet;

XPropertySet aDiaProp = (XPropertySet) UnoRuntime.queryInterface(XPropertySet.class, maDiagram);
Boolean aTrue = new Boolean(true);

aDiaProp.setPropertyValue("Dim3D", aTrue);
aDiaProp.setPropertyValue("Deep", aTrue);

// from service Chart3DBarProperties:
aDiaProp.setPropertyValue("SolidType", new Integer(
com.sun.star.chart.ChartSolidType.CYLINDER));

// change floor color to Magenta6
XPropertySet aFloor = ((X3DDisplay) UnoRuntime.queryInterface(
X3DDisplay.class, maDiagram)).getFloor();
aFloor.setPropertyValue("FillColor", new Integer(0x6b2394));

// rotate the scene using a homogen 4x4 matrix
// -------------------------------------------
HomogenMatrix aMatrix = new HomogenMatrix();
// initialize matrix with identity
HomogenMatrixLine aLines[] = new HomogenMatrixLine[] {
new HomogenMatrixLine(1.0, 0.0, 0.0, 0.0),
new HomogenMatrixLine(0.0, 1.0, 0.0, 0.0),
new HomogenMatrixLine(0.0, 0.0, 1.0, 0.0),
new HomogenMatrixLine(0.0, 0.0, 0.0, 1.0)
};

aMatrix.Line1 = aLines[0];
aMatrix.Line2 = aLines[1];
aMatrix.Line3 = aLines[2];
aMatrix.Line4 = aLines[3];

// rotate 10 degrees along the x axis
double fAngle = 10.0;
double fCosX = Math.cos(Math.toRadians(fAngle));
double fSinX = Math.sin(Math.toRadians(fAngle));

// rotate -20 degrees along the y axis
fAngle = -20.0;
double fCosY = Math.cos(Math.toRadians(fAngle));
double fSinY = Math.sin(Math.toRadians(fAngle));

// rotate -5 degrees along the z axis
fAngle = -5.0;
double fCosZ = Math.cos(Math.toRadians(fAngle));
double fSinZ = Math.sin(Math.toRadians(fAngle));

// set the matrix such that it represents all three rotations in the order
// rotate around x axis then around y axis and finally around the z axis
aMatrix.Line1.Column1 = fCosY * fCosZ;
aMatrix.Line1.Column2 = fCosY * -fSinZ;
aMatrix.Line1.Column3 = fSinY;

aMatrix.Line2.Column1 = fSinX * fSinY * fCosZ + fCosX * fSinZ;
aMatrix.Line2.Column2 = -fSinX * fSinY * fSinZ + fCosX * fCosZ;
aMatrix.Line2.Column3 = -fSinX * fCosY;

aMatrix.Line3.Column1 = -fCosX * fSinY * fCosZ + fSinX * fSinZ;
aMatrix.Line3.Column2 = fCosX * fSinY * fSinZ + fSinX * fCosZ;
aMatrix.Line3.Column3 = fCosX * fCosY;

aDiaProp.setPropertyValue("D3DTransformMatrix", aMatrix);

// add a red light source
// ----------------------

// in a chart by default only the second (non-specular) light source is switched on
// light source 1 is the only specular light source that is used here

// set direction
com.sun.star.drawing.Direction3D aDirection = new com.sun.star.drawing.Direction3D();

aDirection.DirectionX = -0.75;
aDirection.DirectionY = 0.5;
aDirection.DirectionZ = 0.5;

aDiaProp.setPropertyValue("D3DSceneLightDirection1", aDirection);
aDiaProp.setPropertyValue("D3DSceneLightColor1", new Integer(0xff3333));
aDiaProp.setPropertyValue("D3DSceneLightOn1", new Boolean(true));
</source>
Refer to [[Documentation/DevGuide/Drawings/Drawing Documents and Presentation Documents|Drawing Documents and Presentation Documents]] for additional details about three-dimensional properties.

{{PDL1}}

[[Category:Documentation/Developer's Guide/Charts]]

BuildSpeedup

2010-01-26T01:18:55Z

Newacct:

Make the OO.o build system the coolest on the planet! OpenOffice.org is one of the largest and most interesting open source projects that exists. The target of the BuildSpeedup project is to make the build system the coolest one around. A reliable and fast build system has several direct and indirect impacts, maybe most importantly it is the first thing a new contributor comes across when they pick up the project. Main main target audience is an contributor running a high-mid level desktop. Secondary target is people running build farms (notably Sun). Specification for Jam build prototype [[SpecJamBuild]].

* Simple test harness to figure out the speed of different build tools: [http://wiki.services.openoffice.org/mwiki/images/1/11/Buildtest.tgz Buildtest.tgz]
* Paper on prototype for setting up and building OO.o on large compilation cluster: [http://wiki.services.openoffice.org/wiki/Image:Build_j50.tgz Build_j50.tgz]

== How to report build profile logs ==

Thank you for sending in a build profile log. The more logs we have, the easier it is to focus our effort correctly. Here are the steps to producing a build log:

# Apply the latest patch from {{Bug|60948}} to your source tree
# in the dmake directory type "make clean; make". In the root directory type "./bootstrap"
# When building redirect stderr and stdout to the logfile. In tcsh "build --all |& tee myconfigdesc_build.log" will do the trick. You can alternatively use cat instead of tee to speed up the build slightly. You need to build in a single go and in a single process (no parallel building)
# Check that the log contains markers like "s target 1234 foo.obj". If not, then report
# Compress the log with zip/gz
# When you send in your log URL to mailto:kaib@openoffice.org please provide a short description of the build type:
#* Important configure options (like --with-lang=?)
#* OS/compiler/generic hardware description
#* No-change, partial or full build (we are especially looking for full builds)
#* External accelerators like [[wikipedia:ccache|ccache]]

Thank you again for contributing! --[[User:KaiB|KaiB]] 16:25, 25 January 2006 (CET)

== Profile results ==

Here are some initial profile results. These were done on a HP development desktop with 4GB of RAM. Due to various reasons there is a margin of error in all results, but the largest culprits are pretty clear.

=== Full rebuild from scratch ===

{| border="1" cellspacing="0" cellpadding="5" align="center"
|-
! Time spent
! Target type (file extension)
|-
| 33.2%
| C/C++ compilation (obj)
|-
| 27%
| dmake/build.pl (time not attributed to any target)
|-
| 22.0%
| Dependency generation (dpcc)
|-
| 3.7%
| SDK installer (sdkoo_en-US)
|-
| 1.3%
| Unknown, build related (last_target)
|-
| 1.2%
| Linking (dll)
|-
| 1.1%
| OpenOffice.org installer (openoffice_en-US)
|}

Running time: 62296 s targets: 45927 s 73%

As a benchmark, a Mozilla Firefox build corrected for differences in source code size takes about 25% of the OO.o build time.

=== Nothing changed rebuild ===

Basically profiling the build in a non-changed source tree.

{| border="1" cellspacing="0" cellpadding="5" align="center"
|-
! Time spent
! Target type (file extension)
|-
| 54.8%
| SDK installer (sdkoo_en-US)
|-
| 19%
| dmake/build.pl (time not attributed to any target)
|-
| 16.2%
| OpenOffice installer (openoffice_en-US)
|}

Running time: 4209 s targets: 3431 s 81%

== Notes ==

This is a workarea for ideas and notes regarding the speeding up of the build process. --[[User:KaiB|KaiB]] 12:50, 16 January 2006 (CET)

Notes:
* Newest dmake version: cws_src680_dmake43p01)
* solenv/inc define global targets
* potential modules: KaiB: transex3, tools, svx, binfilter - small to huge :)
* helpcontent2 --with-lang=ALL (there are open issues on this already)
* batched compiles
* Interix instead of cygwin
* dependency generation

Existing possibly useful Build Speed related tweaks:
* export nodep=true
* export NO_HIDS=true
* build.pl -P parallel flag
* dmake -P parallel flag and/or MAXPROCESS (cws_src680_dmake43p01 has fixes for some problems there)
* dmake -s flag for less verbose output
* for gcj users targetedaot workspace to ahead of time compile (only) HelpLinker and FCFGMerge java build tools

=== transex3 ===

Started by tackling this small module. Initial full compile time was 137 sec.

== build_profile_analyzer.py ==

(NB. Move this to an attachment once the Wiki accepts .py files)

# Copyright 2006 Google Inc.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# OO.o build profile analyzer. To get the required patches look at:
# http://wiki.services.openoffice.org/wiki/BuildSpeedup
# Author: Kai Backman, kaib@google.com

import os
import re
import sys

def SortProfileTimes(lhs, rhs):
if lhs[1] < rhs[1] : return 1
elif rhs[1] < lhs[1] : return -1
else : return 0

def ProcessLogFile(file_name, target_durations):
# print "Processing file: " + file_name
file = open(file_name)
start_time = 0
end_time = 0

target_start = 0
target_name = ""
line = file.readline()
while line != "" :
tokens = line[:-1].split(" ")
line = file.readline()

if len(tokens) < 2 : continue
if tokens[1] == "build" :
if tokens[0] == "s" :
start_time = int(tokens[2]) * 1000
elif tokens[0] == "e" :
end_time = int(tokens[2]) * 1000
elif tokens[1] == "target" :
if tokens[0] == "s":
target_start = int(tokens[2])
target_name = tokens[3]
elif tokens[0] == "e" and target_name == tokens[3]:
target_duration = int(tokens[2]) - target_start
target_tokens = tokens[3].split(".")
target_class = target_tokens[-1]
if target_class in target_durations :
target_durations[target_class] += target_duration
else :
target_durations[target_class] = target_duration
file.close()
return end_time - start_time
return

if __name__ == "__main__":
target_durations = {}
total_time = 0
for file_name in sys.argv[1:] :
total_time += ProcessLogFile(file_name, target_durations)

profile = target_durations.items()
profile.sort(SortProfileTimes)
total_target_time = 0
for target_iter in profile :
target_promille = target_iter[1] * 1000 / total_time
if target_promille > 0 :
print "%6.ds %3.d.%1.d%% %s" % (target_iter[1] / 1000, target_promille/10,
target_promille % 10, target_iter[0])
total_target_time += target_iter[1]
print "Running time: %d s targets: %d s %d%%" % (total_time / 1000, total_target_time / 1000,
total_target_time * 100 / total_time)

[[Category:Development]]
[[Category:Build_System]]

OpenOffice Add-On Project Type

2010-01-24T12:23:37Z

Newacct:

Back to [[OpenOffice_NetBeans_Integration|OpenOffice.org NetBeans Integration]]

= Overview =

The Add-On wizard will enable users to create an OpenOffice.org component that including support of UI extensions. The component is based on a on a J2SE class library project and supports additional targets to create and deploy the package into the office installation.
All interface methods are default implemented and do nothing. In a second step you can insert your implementation in the generated skeleton, rebuild the extension and deploy it again to see the effect in your office.

= Project Wizard =
The project wizard is quite simple to use, you simply choose
*'' '''File -> New Project -> OpenOffice.org -> OpenOffice.org Add-On''' ''
and follow the wizard.

* '''Step 1''': Select the project type [[Image:AddOn1.png|center]] 
* '''Step 2''': Define the project name, Add-On name, an optional package and the project location [[Image:AddOn2.png|center]] The necessary xcu files are generated and become part of the final '''oxt''' package. These xcu files can be easily adapted later to extend the initial project to a more complex Add-On example. The generated Add-On skeleton implements a simple [http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/WritingUNO/Protocol_Handler com.sun.star.frame.ProtocolHandler] Add-On. 
* '''Step 3''': Defining the new commands, including icons. [[Image:AddOn3-1.png|center]] 
* '''Step 4''': Defining the top level menu [[Image:AddOn3.png|center]] On this panel you can define the top level menus with sub-menus on a higher abstraction level. You will not have to deal with xcu files directly. You can modify the default menu, add new menus and commands, and you can define the context in which the command should appear. When you have deployed the package, the newly defined menus are visible in the specified context. For example, if you choose the context '''Writer''', the menu is visible when you open or create a text document. Not selecting a context means all contexts, even the back-end window. For more detailed descriptions of the different fields simply press the help button or read the appropriate chapter in the [http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/WritingUNO/Protocol_Handler Protocol Handler] [[Image:AddOn4.png|center]] 
* '''Step 5''': Definig the toolbar is similar to the menu. There is no top level toolbar, of course. [[Image:AddOn5.png|center]] 
* '''Step 6''': Deploying the extension package [[Image:Calc_AddIn4.png|center]] You can simply create or deploy the '''oxt''' extension package by choosing: '''Project View -> Project Node -> Context Menu -> Deploy and Run Extension in OpenOffice.org'''

The AddOn deployed in OpenOffice.org is visible in the back-end window. [[Image:AddOn6.png|center]]

= Generated Code =
Two (.xcu) files for the Add-On are created that describe the Add-On commands with descriptions, displaynames etc., (Addons.xcu) and the protocol that is used to access these commands (ProtocolHandler.xcu). For the example shown above, the following files are generated:

* '''Addons.xcu''' xcu file defining the new menus with submenus and commands. This file can be easily extended to support toolbars as well (toolbar support will be added later to the wizard).
<source lang="xml">
<?xml version='1.0' encoding='UTF-8'?>

<oor:component-data xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" oor:name="Addons" oor:package="org.openoffice.Office">
<node oor:name="AddonUI">
<node oor:name="OfficeMenuBar">
<node oor:name="org.openoffice.testaddon.testaddon" oor:op="replace">
<prop oor:name="Title" oor:type="xs:string">
<value/>
<value xml:lang="en">My Menu</value>
</prop>
<prop oor:name="Target" oor:type="xs:string">
<value>_self</value>
</prop>
<prop oor:name="ImageIdentifier" oor:type="xs:string">
<value/>
</prop>
<node oor:name="Submenu">
<node oor:name="m1" oor:op="replace">
<prop oor:name="URL" oor:type="xs:string">
<value>org.openoffice.testaddon.testaddon:HelloWorld</value>
</prop>
<prop oor:name="ImageIdentifier" oor:type="xs:string">
<value/>
</prop>
<prop oor:name="Target" oor:type="xs:string">
<value>_self</value>
</prop>
<prop oor:name="Context" oor:type="xs:string">
<value/>
</prop>
<prop oor:name="Title" oor:type="xs:string">
<value/>
<value xml:lang="en">Hello World</value>
</prop>
</node>
</node>
</node>
</node>
<node oor:name="OfficeToolBar">
<node oor:name="org.openoffice.testaddon.testaddon" oor:op="replace">
<node oor:name="m1" oor:op="replace">
<prop oor:name="URL" oor:type="xs:string">
<value>org.openoffice.testaddon.testaddon:HelloWorld</value>
</prop>
<prop oor:name="ImageIdentifier" oor:type="xs:string">
<value/>
</prop>
<prop oor:name="Target" oor:type="xs:string">
<value>_self</value>
</prop>
<prop oor:name="Context" oor:type="xs:string">
<value/>
</prop>
<prop oor:name="Title" oor:type="xs:string">
<value/>
<value xml:lang="en">Hello World</value>
</prop>
</node>
</node>
</node>
<node oor:name="Images">
<node oor:name="org.openoffice.testaddon.testaddon.helloworld.images" oor:op="replace">
<prop oor:name="URL" oor:type="xs:string">
<value>org.openoffice.testaddon.testaddon:HelloWorld</value>
</prop>
<node oor:name="UserDefinedImages">
<prop oor:name="ImageSmallURL">
<value>%origin%/idlfile.png</value>
</prop>
<prop oor:name="ImageBigURL">
<value>%origin%/idlfile.png</value>
</prop>
<prop oor:name="ImageSmallHCURL">
<value>%origin%/idlfile.png</value>
</prop>
<prop oor:name="ImageBigHCURL">
<value>%origin%/idlfile.png</value>
</prop>
</node>
</node>
</node>
</node>
</oor:component-data>
</source>
* '''uno-extension-manifest.xml''' the package descriptor, will be packed as "META-INF/manifest.xml"
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<manifest:manifest xmlns:manifest="http://openoffice.org/2001/manifest">
<manifest:file-entry manifest:media-type="application/vnd.sun.star.uno-component;type=Java"
manifest:full-path="TestAddOn.jar"/>
<manifest:file-entry manifest:media-type="application/vnd.sun.star.configuration-data"
manifest:full-path="registry/data/org/openoffice/Office/Addons.xcu"/>
<manifest:file-entry manifest:media-type="application/vnd.sun.star.configuration-data"
manifest:full-path="registry/data/org/openoffice/Office/ProtocolHandler.xcu"/>
</manifest:manifest>
</source>

* '''org/openoffice/testaddon/TestAddOn.java''' the generated Add-On code skeleton where the generated class acts itself as the dispatch object (can be easily changed to support more complex Add-Ons). Most of the methods are already implemented and you simply have to add your own code in the dispatch method in the right place for each specified command.
<source lang="Java">
package org.openoffice.testaddon;

import com.sun.star.uno.UnoRuntime;
import com.sun.star.uno.XComponentContext;
import com.sun.star.lib.uno.helper.Factory;
import com.sun.star.lang.XSingleComponentFactory;
import com.sun.star.registry.XRegistryKey;
import com.sun.star.lib.uno.helper.WeakBase;

public final class TestAddOn extends WeakBase
implements com.sun.star.lang.XServiceInfo,
com.sun.star.frame.XDispatchProvider,
com.sun.star.lang.XInitialization,
com.sun.star.frame.XDispatch
{
private final XComponentContext m_xContext;
private com.sun.star.frame.XFrame m_xFrame;
private static final String m_implementationName = TestAddOn.class.getName();
private static final String[] m_serviceNames = {
"com.sun.star.frame.ProtocolHandler" };

public TestAddOn( XComponentContext context )
{
m_xContext = context;
};

public static XSingleComponentFactory __getComponentFactory( String sImplementationName ) {
XSingleComponentFactory xFactory = null;

if ( sImplementationName.equals( m_implementationName ) )
xFactory = Factory.createComponentFactory(TestAddOn.class, m_serviceNames);
return xFactory;
}

public static boolean __writeRegistryServiceInfo( XRegistryKey xRegistryKey ) {
return Factory.writeRegistryServiceInfo(m_implementationName,
m_serviceNames,
xRegistryKey);
}

// com.sun.star.lang.XServiceInfo:
public String getImplementationName() {
return m_implementationName;
}

public boolean supportsService( String sService ) {
int len = m_serviceNames.length;

for( int i=0; i < len; i++) {
if (sService.equals(m_serviceNames[i]))
return true;
}
return false;
}

public String[] getSupportedServiceNames() {
return m_serviceNames;
}

// com.sun.star.frame.XDispatchProvider:
public com.sun.star.frame.XDispatch queryDispatch( com.sun.star.util.URL aURL,
String sTargetFrameName,
int iSearchFlags )
{
if ( aURL.Protocol.equals("org.openoffice.testaddon.testaddon:") )
{
if ( aURL.Path.equals("mycommands") )
return this;
}
return null;
}

// com.sun.star.frame.XDispatchProvider:
public com.sun.star.frame.XDispatch[] queryDispatches(
com.sun.star.frame.DispatchDescriptor[] seqDescriptors )
{
int nCount = seqDescriptors.length;
com.sun.star.frame.XDispatch[] seqDispatcher =
new com.sun.star.frame.XDispatch[seqDescriptors.length];

for( int i=0; i < nCount; ++i )
{
seqDispatcher[i] = queryDispatch(seqDescriptors[i].FeatureURL,
seqDescriptors[i].FrameName,
seqDescriptors[i].SearchFlags );
}
return seqDispatcher;
}

// com.sun.star.lang.XInitialization:
public void initialize( Object[] object )
throws com.sun.star.uno.Exception
{
if ( object.length > 0 )
{
m_xFrame = (com.sun.star.frame.XFrame)UnoRuntime.queryInterface(
com.sun.star.frame.XFrame.class, object[0]);
}
}

// com.sun.star.frame.XDispatch:
public void dispatch( com.sun.star.util.URL aURL,
com.sun.star.beans.PropertyValue[] aArguments )
{
if ( aURL.Protocol.equals("org.openoffice.testaddon.testaddon:") )
{
if ( aURL.Path.equals("mycommands") )
{
// add your own code here
return;
}
}
}

public void addStatusListener( com.sun.star.frame.XStatusListener xControl,
com.sun.star.util.URL aURL )
{
// add your own code here
}

public void removeStatusListener( com.sun.star.frame.XStatusListener xControl,
com.sun.star.util.URL aURL )
{
// add your own code here
}

}
</source>

[[Category:Uno]]
[[Category:Development]]
[[Category:Add-On]]
[[Category:API]]

Documentation/DevGuide/Basic/Creating Dialogs at Runtime

2010-01-22T09:11:33Z

Newacct:

{{Documentation/DevGuide/BasicTOC
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Basic/File Control
|NextPage=Documentation/DevGuide/Basic/Library File Structure
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Basic/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Creating Dialogs at Runtime}}
When using {{PRODUCTNAME}} Basic, the dialog editor is a tool for designing dialogs. Refer to [[Documentation/DevGuide/Basic/OpenOffice.org Basic IDE|OpenOffice.org Basic IDE]] for additional information. Since {{PRODUCTNAME}} {{OO2.0.0}}, dialogs that have been built with the dialog editor can be loaded by a macro written in any of the supported scripting framework languages (BeanShell, JavaScript, Java, {{PRODUCTNAME}} Basic) by using the <idl>com.sun.star.awt.XDialogProvider</idl> API. See section [[Documentation/DevGuide/Scripting/Using the Scripting Framework|Using the Scripting Framework]] for more details.

In addition, it is also possible to create dialogs at runtime in a similar way as Java Swing components are created. Also, the event listeners are registered at runtime at the appropriate controls.

[[Image:CreatingDialogs_SampleDialog.png|none|thumb|295px|An example dialog]]

In the Java example described in this section, a simple modal dialog is created at runtime containing a command button and label field. Each time the user clicks on the button, the label field is updated and the total number of button clicks is displayed.

The dialog is implemented as a UNO component in Java that is instantiated with the service name <code>com.sun.star.examples.SampleDialog</code>. For details about writing a Java component and the implementation of the UNO core interfaces, refer to [[Documentation/DevGuide/WritingUNO/Storing the Service Manager for Further Use|Storing the Service Manager for Further Use]]. The method that creates and executes the dialog is shown below.

<source lang="java">
/** method for creating a dialog at runtime
*/
private void createDialog() throws com.sun.star.uno.Exception {
// get the service manager from the component context
XMultiComponentFactory xMultiComponentFactory = _xComponentContext.getServiceManager();
// create the dialog model and set the properties
Object dialogModel = xMultiComponentFactory.createInstanceWithContext(
"com.sun.star.awt.UnoControlDialogModel", _xComponentContext);
XPropertySet xPSetDialog = (XPropertySet)UnoRuntime.queryInterface(
XPropertySet.class, dialogModel);
xPSetDialog.setPropertyValue("PositionX", new Integer(100));
xPSetDialog.setPropertyValue("PositionY", new Integer(100));
xPSetDialog.setPropertyValue("Width", new Integer(150));
xPSetDialog.setPropertyValue("Height", new Integer(100));
xPSetDialog.setPropertyValue("Title", new String("Runtime Dialog Demo"));
// get the service manager from the dialog model
XMultiServiceFactory xMultiServiceFactory = (XMultiServiceFactory)UnoRuntime.queryInterface(
XMultiServiceFactory.class, dialogModel);
// create the button model and set the properties
Object buttonModel = xMultiServiceFactory.createInstance(
"com.sun.star.awt.UnoControlButtonModel" );
XPropertySet xPSetButton = (XPropertySet)UnoRuntime.queryInterface(
XPropertySet.class, buttonModel);
xPSetButton.setPropertyValue("PositionX", new Integer(50));
xPSetButton.setPropertyValue("PositionY", new Integer(30));
xPSetButton.setPropertyValue("Width", new Integer(50));
xPSetButton.setPropertyValue("Height", new Integer(14));
xPSetButton.setPropertyValue("Name", _buttonName);
xPSetButton.setPropertyValue("TabIndex", new Short((short)0));
xPSetButton.setPropertyValue("Label", new String("Click Me"));
// create the label model and set the properties
Object labelModel = xMultiServiceFactory.createInstance(
"com.sun.star.awt.UnoControlFixedTextModel" );
XPropertySet xPSetLabel = ( XPropertySet )UnoRuntime.queryInterface(
XPropertySet.class, labelModel );
xPSetLabel.setPropertyValue("PositionX", new Integer(40));
xPSetLabel.setPropertyValue("PositionY", new Integer(60));
xPSetLabel.setPropertyValue("Width", new Integer(100));
xPSetLabel.setPropertyValue("Height", new Integer(14));
xPSetLabel.setPropertyValue("Name", _labelName);
xPSetLabel.setPropertyValue("TabIndex", new Short((short)1));
xPSetLabel.setPropertyValue("Label", _labelPrefix);
// insert the control models into the dialog model
XNameContainer xNameCont = (XNameContainer)UnoRuntime.queryInterface(
XNameContainer.class, dialogModel);
xNameCont.insertByName(_buttonName, buttonModel);
xNameCont.insertByName(_labelName, labelModel);
// create the dialog control and set the model
Object dialog = xMultiComponentFactory.createInstanceWithContext(
"com.sun.star.awt.UnoControlDialog", _xComponentContext);
XControl xControl = (XControl)UnoRuntime.queryInterface(
XControl.class, dialog );
XControlModel xControlModel = (XControlModel)UnoRuntime.queryInterface(
XControlModel.class, dialogModel);
xControl.setModel(xControlModel);
// add an action listener to the button control
XControlContainer xControlCont = (XControlContainer)UnoRuntime.queryInterface(
XControlContainer.class, dialog);
Object objectButton = xControlCont.getControl("Button1");
XButton xButton = (XButton)UnoRuntime.queryInterface(XButton.class, objectButton);
xButton.addActionListener(new ActionListenerImpl(xControlCont));
// create a peer
Object toolkit = xMultiComponentFactory.createInstanceWithContext(
"com.sun.star.awt.Toolkit", _xComponentContext);
XToolkit xToolkit = (XToolkit)UnoRuntime.queryInterface(XToolkit.class, toolkit);
XWindow xWindow = (XWindow)UnoRuntime.queryInterface(XWindow.class, xControl);
xWindow.setVisible(false);
xControl.createPeer(xToolkit, null);
// execute the dialog
XDialog xDialog = (XDialog)UnoRuntime.queryInterface(XDialog.class, dialog);
xDialog.execute();
// dispose the dialog
XComponent xComponent = (XComponent)UnoRuntime.queryInterface(XComponent.class, dialog);
xComponent.dispose();
}
</source>
First, a dialog model is created by prompting the <code>ServiceManager</code> for the <idl>com.sun.star.awt.UnoControlDialogModel</idl> service. Then, the position, size and title of the dialog are set using the <idl>com.sun.star.beans.XPropertySet</idl> interface. In performance critical applications, the use of the <idl>com.sun.star.beans.XMultiPropertySet</idl> interface is recommended. At this point, the dialog model describes an empty dialog, which does not contain any control models.

All control models in a dialog container have the common properties "PositionX", "PositionY", "Width", "Height", "Name", "TabIndex", "Step" and "Tag". These properties are optional and only added if the control model is created by a special object factory, namely the dialog model. Therefore, a dialog model also supports the <idl>com.sun.star.lang.XMultiServiceFactory</idl> interface. If the control model is created by the <code>ServiceManager</code>, these common properties are missing.

{{Documentation/Note|Note that control models have the common properties "PositionX", "PositionY", "Width", "Height", "Name", "TabIndex", "Step" and "Tag" only if they were created by the dialog model that they belong to.}}

After the control models for the command button and label field are created, their position, size, name, tab index and label are set. Then, the control models are inserted into the dialog model using the <idl>com.sun.star.container.XNameContainer</idl> interface. The model of the dialog has been fully described.

To display the dialog on the screen, a dialog control <idl>com.sun.star.awt.UnoControlDialog</idl> is created and the corresponding model is set. An action listener is added to the button control, because the label field is updated whenever the user clicks on the command button. The listener is explained below. Before the dialog is shown, a window or a peer is created on the screen. Finally, the dialog is displayed on the screen using the execute method of the <idl>com.sun.star.awt.XDialog</idl> interface.

The implementation of the action listener is shown in the following example.

/** action listener
*/
public class ActionListenerImpl implements com.sun.star.awt.XActionListener {
private int _nCounts = 0;
private XControlContainer _xControlCont;

public ActionListenerImpl(XControlContainer xControlCont) {
_xControlCont = xControlCont;
}

// XEventListener
public void disposing(EventObject eventObject) {
_xControlCont = null;
}

// XActionListener
public void actionPerformed(ActionEvent actionEvent) {
// increase click counter
_nCounts++;

// set label text
Object label = _xControlCont.getControl("Label1");
XFixedText xLabel = (XFixedText)UnoRuntime.queryInterface(XFixedText.class, label);
xLabel.setText(_labelPrefix + _nCounts);
}
}

The action listener is fired each time the user clicks on the command button. In the <code>actionPerformed</code> method of the <idl>com.sun.star.awt.XActionListener</idl> interface, an internal counter for the number of button clicks is increased. Then, this number is updated in the label field. In addition, the disposing method of the parent interface <idl>com.sun.star.lang.XEventListener</idl> is implemented.

Our sample component executes the dialog from within the office by implementing the trigger method of the <idl>com.sun.star.task.XJobExecutor</idl> interface:

public void trigger(String sEvent) {
if (sEvent.equals("execute")) {
try {
createDialog();
}
catch (Exception e) {
throw new com.sun.star.lang.WrappedTargetRuntimeException(e.getMessage(), this, e);
}
}
}

A simple {{PRODUCTNAME}} Basic macro that instantiates the service of our sample component and executes the dialog is shown below.

Sub Main
Dim oJobExecutor
oJobExecutor = CreateUnoService("com.sun.star.examples.SampleDialog")
oJobExecutor.trigger("execute")
End Sub

In future versions of {{PRODUCTNAME}}, a method for executing dialogs created at runtime will be provided.

{{PDL1}}

[[Category:Documentation/Developer's Guide/Basic and Dialogs]]

Performance/Startup

2009-12-14T19:14:49Z

Newacct: /* callgrind */

{{Performance}}
= Issues =

* [http://eis.services.openoffice.org/EIS2/cws.ShowCWS?Path=DEV300%2Fsb103 CWS sb103], integrated in OOO310_m1 and DEV300_m42:
** [http://qa.openoffice.org/issues/show_bug.cgi?id=96284 Issue 96284] “registry symlink foo ...”
** [http://qa.openoffice.org/issues/show_bug.cgi?id=97424 Issue 97424] “improve ImplImageTree performance”
* [http://eis.services.openoffice.org/EIS2/cws.ShowCWS?Path=DEV300%2Fsb107 CWS sb107], integrated in DEV300_m47:
** [http://qa.openoffice.org/issues/show_bug.cgi?id=85679 Issue 85679] “Link with -Wl,-Bsymbolic-functions -Wl,--dynamic-list-cpp-new -Wl,--dynamic-list-cpp-typeinfo when supported”
** [http://qa.openoffice.org/issues/show_bug.cgi?id=99519 Issue 99519] “Remove unnecessary library dependencies” (“[t]his cleanup has no positive impact on OOo startup performance though”—[https://so-web.germany.sun.com/iBIS/servlet/edit.ControlPanel?tid=i99519#desc3])
** [http://qa.openoffice.org/issues/show_bug.cgi?id=100348 Issue 100348] “svt, bf_svt export symbols from jpeg archive”
** [http://qa.openoffice.org/issues/show_bug.cgi?id=100396 Issue 100396] “svtools: costly external data symbols sHTML_xxx/sRTF_xxx”
** [http://qa.openoffice.org/issues/show_bug.cgi?id=100576 Issue 100576] “enable HAVE_LD_HASH_STYLE in sdev300.ini”
* analyzing startup to identify performance problems (ongoing)

= Details =

== Additional processes during startup ==

Starting OOo <code>DEV300m39</code> <code>unxlngi6.pro</code> on <code>v20z-so3</code> (some old Ubuntu machine), <code>soffice.bin</code> spawns additional processes during start up:

<pre>
$ strace -fF opt/openoffice.org3/program/soffice.bin 2>&1 | grep 'exec.*('
execve("ooo/opt/openoffice.org3/program/soffice.bin", ["ooo/opt/openoffice.org3/program/"...], [/* 17 vars */]) = 0
[pid 19800] execve("/usr/lib/libgconf2-4/gconfd-2", ["/usr/lib/libgconf2-4/gconfd-2", "17"], [/* 18 vars */] <unfinished ...>
[pid 19802] execve("/bin/sh", ["sh", "-c", "sh -c paperconf 2>/dev/null"], [/* 18 vars */]) = 0
[pid 19803] execve("/bin/sh", ["sh", "-c", "paperconf"], [/* 17 vars */]) = 0
</pre>

It turns out only the first additional process (<code>/usr/lib/libgconf2-4/gconfd-2</code>) is spawned directly from <code>soffice.bin</code> (and the following ones are in turn spawned from that process), and it is spawned during a call to <code>gconf_client_preload</code>:

<pre>
$ gdb opt/openoffice.org3/program/soffice.bin
(gdb) break fork
Breakpoint 2 at 0xb7c6f584
(gdb) run
Breakpoint 2, 0xb7c6f584 in fork () from /lib/tls/i686/cmov/libpthread.so.0
(gdb) info threads
4 Thread -1296356432 (LWP 19893) 0xffffe410 in __kernel_vsyscall ()
3 Thread -1287963728 (LWP 19892) 0xffffe410 in __kernel_vsyscall ()
2 Thread -1251386448 (LWP 19889) 0xffffe410 in __kernel_vsyscall ()
* 1 Thread -1251252000 (LWP 19887) 0xb7c6f584 in fork ()
from /lib/tls/i686/cmov/libpthread.so.0
(gdb) where
#0 0xb7c6f584 in fork () from /lib/tls/i686/cmov/libpthread.so.0
#1 0xb496593a in g_spawn_error_quark () from /usr/lib/libglib-2.0.so.0
#2 0xb49660fe in g_spawn_async_with_pipes () from /usr/lib/libglib-2.0.so.0
#3 0xb496617b in g_spawn_async () from /usr/lib/libglib-2.0.so.0
#4 0xb34a4ec6 in gconf_activate_server () from /usr/lib/libgconf-2.so.4
#5 0xb34afc29 in gconf_debug_shutdown () from /usr/lib/libgconf-2.so.4
#6 0xb34b06e1 in gconf_spawn_daemon () from /usr/lib/libgconf-2.so.4
#7 0xb34b091a in gconf_spawn_daemon () from /usr/lib/libgconf-2.so.4
#8 0xb34b148c in gconf_engine_all_entries () from /usr/lib/libgconf-2.so.4
#9 0xb34b7540 in gconf_client_all_entries () from /usr/lib/libgconf-2.so.4
#10 0xb34e0f9c in GconfLayer::getTimestamp (this=0xb342dc1c)
at /so/ws/DEV300/ooo/shell/source/backends/gconfbe/gconflayer.cxx:528
#11 0xb35dc4c3 in configmgr::backend::BinaryReadHandler::validateHeader (
this=0xbffcf42c, pLayers=0xb33c2020, nNumLayers=6,
_aSchemaVersion=@0xbffcf550, aRequestedLocale=@0xbffcf530,
outKnownLocales=@0xbffcf540) at Reference.h:366
#12 0xb35dd151 in configmgr::backend::BinaryCache::readComponentData (
this=0xb33bca1c, aComponentData=@0xbffcf698, aFactory=@0xbffcf510,
aComponent=@0xbffcf6c8, aSchemaVersion=@0xbffcf550, aEntity=@0xbffcf520,
aRequestedLocale=@0xbffcf530, outKnownLocales=@0xbffcf540,
pLayers=0xb33c2020, nNumLayers=6, bIncludeTemplates=true)
at /so/ws/DEV300/ooo/configmgr/source/backend/binarycache.cxx:200
#13 0xb35cc7bd in configmgr::backend::BackendAccess::readDefaultData (
this=0xb4584d5c, aComponentData=@0xbffcf698, aComponent=@0xbffcf6c8,
aOptions=@0xbffcf83c, bIncludeTemplates=true, pLayers=0xb33c2020,
nNumLayers=6, aTemplateProvider=0xb352d60c, pLayersMerged=0xbffcf644)
at /so/ws/DEV300/ooo/configmgr/source/backend/backendaccess.cxx:84
#14 0xb35cd9bd in configmgr::backend::BackendAccess::getNodeData (
this=0xb4584d5c, aRequest=@0xbffcf838, _aTemplateProvider=0xb352d60c,
aListener=0xb352d610) at request.hxx:75
#15 0xb35934e5 in configmgr::backend::CacheController::loadDirectly (
this=0xb352d604, _aRequest=@0xbffcf838, _bAddListenter=true) at ref.hxx:167
#16 0xb3597198 in configmgr::backend::CacheController::loadComponent (
this=0xb352d604, _aRequest=@0xbffcf838)
at /so/ws/DEV300/ooo/configmgr/source/treecache/cachecontroller.cxx:376
#17 0xb359b6d4 in configmgr::TreeManager::requestSubtree (this=0xb4584eac,
aSubtreePath=@0xbffcf960, _aOptions=@0xbffcf83c) at ref.hxx:99
#18 0xb36517e9 in configmgr::OProviderImpl::requestSubtree (this=0xb458b31c,
aSubtreePath=@0xbffcf960, _aOptions=@0xbffcf9a0) at ref.hxx:167
#19 0xb3652f6b in configmgr::OProviderImpl::buildReadAccess (this=0xb458b31c,
_rAccessor=@0xbffcf9c0, _aOptions=@0xbffcf9a0, nMinLevels=-1)
at /so/ws/DEV300/ooo/configmgr/source/api2/providerimpl.cxx:490
#20 0xb36532b5 in configmgr::OProviderImpl::createReadAccess (this=0xb458b31c,
aArgs=@0xbffcfb80)
at /so/ws/DEV300/ooo/configmgr/source/api2/providerimpl.cxx:860
#21 0xb364b799 in configmgr::OProvider::createInstanceWithArguments (
this=0xb376a554, aServiceSpecifier=@0xbffcfb20, aArguments=@0xbffcfb80)
at Reference.h:359
#22 0xb690b180 in DefaultFontConfiguration (this=0xb33c3394) at Reference.h:366
#23 0xb690ba5f in vcl::DefaultFontConfiguration::get ()
at /so/ws/DEV300/ooo/vcl/source/gdi/fontcfg.cxx:107
#24 0xb684818d in ImplStyleData::SetStandardStyles (this=0xb33df618)
at ustring.hxx:111
#25 0xb6848945 in ImplStyleData (this=0xb33df618)
at /so/ws/DEV300/ooo/vcl/source/app/settings.cxx:438
#26 0xb6848eef in StyleSettings (this=0x0)
at /so/ws/DEV300/ooo/vcl/source/app/settings.cxx:640
#27 0xb684aa98 in ImplAllSettingsData (this=0xb33b71c8)
at /so/ws/DEV300/ooo/vcl/source/app/settings.cxx:1523
#28 0xb684b244 in AllSettings (this=0x0)
at /so/ws/DEV300/ooo/vcl/source/app/settings.cxx:1590
#29 0xb684ce12 in Application::GetSettings ()
at /so/ws/DEV300/ooo/vcl/source/app/svapp.cxx:814
#30 0xb68c699c in OutputDevice (this=0xb458e924)
at /so/ws/DEV300/ooo/vcl/source/gdi/outdev.cxx:427
#31 0xb6a18618 in Window (this=0xb458e924, nType=383)
at /so/ws/DEV300/ooo/vcl/source/window/window.cxx:4288
#32 0xb69ee0b7 in SystemWindow (this=0xb458e924, nType=0)
at /so/ws/DEV300/ooo/vcl/source/window/syswin.cxx:83
#33 0xb6a28a72 in WorkWindow (this=0xb458e924, nType=0)
at /so/ws/DEV300/ooo/vcl/source/window/wrkwin.cxx:114
#34 0xb69c8151 in IntroWindow (this=0xb458e924)
at /so/ws/DEV300/ooo/vcl/source/window/introwin.cxx:61
#35 0xb239185d in SplashScreen (this=0xb458e908, rSMgr=@0x0)
at /so/ws/DEV300/ooo/desktop/source/splash/splash.cxx:83
#36 0xb2391b10 in desktop::SplashScreen::getInstance (rSMgr=@0xbffcfdec)
at weak.hxx:91
#37 0xb77d9206 in cppu::OSingleFactoryHelper::createInstanceEveryTime (
this=0xb33b726c, xContext=@0x1) at Reference.h:359
#38 0xb77d88be in cppu::OSingleFactoryHelper::createInstanceWithContext (
this=0x0, xContext=@0xb4e41ad8) at Reference.h:359
#39 0xb77d8cb1 in cppu::OFactoryComponentHelper::createInstanceWithContext (
this=0xb33b7238, xContext=@0xb4e41ad8) at Reference.h:359
#40 0xb77d9988 in cppu::OSingleFactoryHelper::createInstanceWithArgumentsAndContext (this=0x0, rArguments=@0xbffd0160, xContext=@0xb4e41ad8) at Reference.h:359
#41 0xb77da48e in cppu::OFactoryComponentHelper::createInstanceWithArgumentsAndContext (this=0xb33b7238, rArguments=@0xbffd0160, xContext=@0xb4e41ad8)
at Reference.h:359
#42 0xb77dadce in cppu::ORegistryFactoryHelper::createInstanceWithArgumentsAndContext (this=0xb33b4264, rArguments=@0xbffd0160, xContext=@0xb4e41ad8)
at Reference.h:366
#43 0xb45f68e9 in stoc_smgr::OServiceManager::createInstanceWithArgumentsAndContext (this=0xb33b42a0, rServiceSpecifier=@0xbffd0130, rArguments=@0xbffd0160,
xContext=@0xb4e41ad8) at Reference.h:366
#44 0xb45f61a8 in stoc_smgr::OServiceManager::createInstanceWithArguments (
this=0x1, rServiceSpecifier=@0xbffd0130, rArguments=@0xbffd0160)
at Reference.h:359
#45 0xb7dbcc21 in desktop::Desktop::OpenSplashScreen (this=0xbffd04a4)
at Reference.h:121
#46 0xb7dbd296 in desktop::Desktop::Main (this=0xbffd04a4)
at /so/ws/DEV300/ooo/desktop/source/app/app.cxx:1232
#47 0xb6852372 in ImplSVMain ()
at /so/ws/DEV300/ooo/vcl/source/app/svmain.cxx:194
#48 0xb68524fd in SVMain () at /so/ws/DEV300/ooo/vcl/source/app/svmain.cxx:235
#49 0xb7de6e23 in soffice_main ()
at /so/ws/DEV300/ooo/desktop/source/app/sofficemain.cxx:52
#50 0x08048dea in main (argc=1, argv=0xbffd0584) at main.c:38
(gdb) cont
Program exited normally.
(gdb) quit
</pre>

The first call to <code>gconf_client_preload</code> (that presumably does the spawning) accounts for 0.05 seconds of real time during start up:

<pre>
$ patch -p 0 <<-\EOF
Index: tags/DEV300_m39/shell/source/backends/gconfbe/gconflayer.cxx
===================================================================
--- tags/DEV300_m39/shell/source/backends/gconfbe/gconflayer.cxx (revision 266425)
+++ tags/DEV300_m39/shell/source/backends/gconfbe/gconflayer.cxx (working copy)
@@ -1,3 +1,6 @@
+/*SB*/#include<stdio.h>
+/*SB*/#include<sys/times.h>
+/*SB*/#include<unistd.h>
/*************************************************************************
*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
@@ -524,8 +527,10 @@
GConfValue* aGconfValue;
int i = 0;

+/*SB*/tms TMS;clock_t TIME=times(&TMS);
while( m_pPreloadValuesList[i] != NULL )
gconf_client_preload( aClient, m_pPreloadValuesList[i++], GCONF_CLIENT_PRELOAD_ONELEVEL, NULL );
+/*SB*/TIME=times(&TMS)-TIME;fprintf(stderr,"time %f\n",double(TIME)/sysconf(_SC_CLK_TCK));for(int N=0;N<i;++N)fprintf(stderr," preload %d <%s>\n",N,m_pPreloadValuesList[N]);

for( i = 0; i < m_nConfigurationValues; i++ )
{
EOF
</pre>

<pre>
$ opt/openoffice.org3/program/soffice.bin
time 0.050000
preload 0 </desktop/gnome/interface>
time 0.010000
preload 0 </desktop/gnome/url-handlers/mailto>
time 0.000000
</pre>

The overhead of the <code>soffice</code> wrapper script around <code>soffice.bin</code> is roughly as follows (see [http://qa.openoffice.org/issues/show_bug.cgi?id=97491 issue 97491] “"soffice" now being binary instead of shellscript” for temporary problems with the <code>soffice</code> wrapper script), where <code>javaldx</code> and <code>pagein</code> are among the executables called from the script:

<pre>
$ rm opt/openoffice.org3/program/soffice.bin
$ ln -s /bin/true opt/openoffice.org3/program/soffice.bin
$ time opt/openoffice.org3/program/soffice
real 0m0.170s
user 0m0.060s
sys 0m0.110s
$ time opt/openoffice.org3/program/../basis-link/ure-link/bin/javaldx "-env:INIFILENAME=vnd.sun.star.pathname:${PWD?}/opt/openoffice.org3/program/redirectrc"
/usr/java/jdk1.6.0_03/jre/lib/i386/client:/usr/java/jdk1.6.0_03/jre/lib/i386/native_threads:/usr/java/jdk1.6.0_03/jre/lib/i386
real 0m0.024s
user 0m0.020s
sys 0m0.000s
$ time opt/openoffice.org3/program/../basis-link/program/pagein "-L${PWD?}/opt/openoffice.org3/program/../basis-link/program" @pagein-common
real 0m0.102s
user 0m0.020s
sys 0m0.080s
</pre>

== ELF Dynamic Objects ==

At least on ELF based systems, one factor that controls how much of a dynamic library needs to be loaded in initially are the relocations in the <code>.rel.dyn</code> section (the <code>.rel.plt</code> section is not relevant directly at load time unless you force <code>LD_BIND_NOW</code>). The following gives the number of relocations per ELF dynamic object in a <code>DEV300m41</code> <code>unxlngi6.pro</code> OOo installation (<code>libicudata.so.40.0</code> has no relocations), for some rough guiding numbers:
<pre>
$ cd DEV300m41-unxlngi6.pro-en_US && find opt -type f -exec bash -c 'file "$0" | fgrep -q " ELF " && echo $(readelf -r "$0" | grep "^Relocation section .*rel.dyn" | cut -d " " -f 8) "$0"' {} \; | sort -n
opt/openoffice.org/basis3.0/program/libicudata.so.40.0
1 opt/openoffice.org/basis3.0/program/python.bin
2 opt/openoffice.org/basis3.0/program/gnome-open-url.bin
2 opt/openoffice.org/basis3.0/program/pagein
2 opt/openoffice.org/basis3.0/program/uri-encode
3 opt/openoffice.org3/program/crash_report.bin
3 opt/openoffice.org/basis3.0/program/msfontextract
6 opt/openoffice.org/basis3.0/program/pyuno.so
7 opt/openoffice.org/basis3.0/program/libprldap50.so
7 opt/openoffice.org/basis3.0/program/libtextcat.so
8 opt/openoffice.org3/program/soffice.bin
8 opt/openoffice.org3/program/unopkg.bin
8 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/crypt.so
10 opt/openoffice.org/ure/bin/regmerge
10 opt/openoffice.org/ure/bin/regview
10 opt/openoffice.org/ure/lib/libgcc_s.so.1
11 opt/openoffice.org/basis3.0/program/libcollator_data.so
11 opt/openoffice.org/basis3.0/program/libdict_ja.so
11 opt/openoffice.org/basis3.0/program/libdict_zh.so
11 opt/openoffice.org/basis3.0/program/liberali.so
11 opt/openoffice.org/basis3.0/program/libetili.so
11 opt/openoffice.org/basis3.0/program/libexpli.so
11 opt/openoffice.org/basis3.0/program/libicdli.so
11 opt/openoffice.org/basis3.0/program/libimeli.so
11 opt/openoffice.org/basis3.0/program/libipbli.so
11 opt/openoffice.org/basis3.0/program/libipdli.so
11 opt/openoffice.org/basis3.0/program/libipsli.so
11 opt/openoffice.org/basis3.0/program/libiptli.so
11 opt/openoffice.org/basis3.0/program/libipxli.so
11 opt/openoffice.org/basis3.0/program/libirali.so
11 opt/openoffice.org/basis3.0/program/libitgli.so
11 opt/openoffice.org/basis3.0/program/libofficebean.so
11 opt/openoffice.org/basis3.0/program/libtextconv_dict.so
11 opt/openoffice.org/ure/bin/javaldx
11 opt/openoffice.org/ure/lib/libjpipe.so
12 opt/openoffice.org/ure/bin/regcomp.bin
13 opt/openoffice.org/basis3.0/program/gengal.bin
13 opt/openoffice.org/basis3.0/program/libaggli.so
13 opt/openoffice.org/basis3.0/program/nsplugin
14 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/rgbimg.so
14 opt/openoffice.org/ure/bin/uno.bin
15 opt/openoffice.org/basis3.0/program/libitili.so
15 opt/openoffice.org/basis3.0/program/pluginapp.bin
15 opt/openoffice.org/basis3.0/program/spadmin.bin
16 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/timing.so
16 opt/openoffice.org/ure/lib/libjuh.so
17 opt/openoffice.org/basis3.0/program/libplds4.so
18 opt/openoffice.org/basis3.0/program/libi18nregexpgcc3.so
18 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/syslog.so
19 opt/openoffice.org/ure/lib/librmcxt.so.3
20 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/_weakref.so
21 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/fcntl.so
22 opt/openoffice.org/basis3.0/program/libi18nisolang1gcc3.so
22 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/dl.so
23 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/rotor.so
24 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/xreadlines.so
27 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/grp.so
27 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/nis.so
27 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/pcre.so
28 opt/openoffice.org3/program/libnpsoplugin.so
29 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/md5.so
29 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/sha.so
30 opt/openoffice.org/basis3.0/program/fpicker.uno.so
30 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/select.so
32 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/_random.so
33 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/pwd.so
33 opt/openoffice.org/basis3.0/program/pythonloader.uno.so
34 opt/openoffice.org/basis3.0/program/desktopbe1.uno.so
34 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/_ssl.so
35 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/dbm.so
35 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/imageop.so
37 opt/openoffice.org/basis3.0/program/libindex_data.so
38 opt/openoffice.org/basis3.0/program/libjli_g.so
38 opt/openoffice.org/basis3.0/program/libmozz.so
40 opt/openoffice.org/ure/lib/libuno_salhelpergcc3.so.3
41 opt/openoffice.org/basis3.0/program/libi18nutilgcc3.so
42 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/gdbm.so
42 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/linuxaudiodev.so
42 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/regex.so
44 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/zlib.so
45 opt/openoffice.org/basis3.0/program/libbf_ofali.so
46 opt/openoffice.org/ure/lib/libunsafe_uno_uno.so
47 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/_testcapi.so
47 opt/openoffice.org/ure/lib/libuno_cppu.so.3
51 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/resource.so
52 opt/openoffice.org/ure/lib/libjvmfwk.so.3
54 opt/openoffice.org/basis3.0/program/components/libvcard.so
54 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/time.so
54 opt/openoffice.org/ure/lib/libuno_purpenvhelpergcc3.so.3
55 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/audioop.so
55 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/cmath.so
55 opt/openoffice.org/basis3.0/program/testtool.bin
58 opt/openoffice.org/ure/lib/libgcc3_uno.so
60 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/mmap.so
62 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/binascii.so
63 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/mpz.so
66 opt/openoffice.org/basis3.0/program/libbf_goli.so
66 opt/openoffice.org/ure/lib/libjava_uno.so
69 opt/openoffice.org/ure/lib/libjvmaccessgcc3.so.3
76 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/strop.so
81 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/_csv.so
86 opt/openoffice.org/basis3.0/program/librdf.so.0.0.0
86 opt/openoffice.org/ure/lib/libaffine_uno_uno.so
87 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/_hotshot.so
89 opt/openoffice.org/basis3.0/program/libplc4.so
91 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/parser.so
97 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/cPickle.so
97 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/_locale.so
97 opt/openoffice.org/ure/lib/libreg.so.3
98 opt/openoffice.org/basis3.0/program/libxslt.so.1.1.24
100 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/struct.so
103 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/math.so
116 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/bz2.so
116 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/cStringIO.so
125 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/ossaudiodev.so
128 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/itertools.so
132 opt/openoffice.org/basis3.0/program/libcurl.so.3.0.0
133 opt/openoffice.org/basis3.0/program/libldap50.so
145 opt/openoffice.org/basis3.0/program/libicgli.so
151 opt/openoffice.org/ure/lib/liburp_uno.so
152 opt/openoffice.org/basis3.0/program/libtfuli.so
152 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/array.so
153 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/_socket.so
161 opt/openoffice.org/ure/lib/namingservice.uno.so
163 opt/openoffice.org/basis3.0/program/libepbli.so
163 opt/openoffice.org/basis3.0/program/libepgli.so
163 opt/openoffice.org/basis3.0/program/libeppli.so
164 opt/openoffice.org/basis3.0/program/libegili.so
164 opt/openoffice.org/ure/lib/remotebridge.uno.so
166 opt/openoffice.org/basis3.0/program/libemeli.so
166 opt/openoffice.org/basis3.0/program/libeptli.so
168 opt/openoffice.org/ure/lib/uuresolver.uno.so
169 opt/openoffice.org/basis3.0/program/libsmdli.so
170 opt/openoffice.org/basis3.0/program/i18nsearch.uno.so
170 opt/openoffice.org/basis3.0/program/libswdli.so
171 opt/openoffice.org/basis3.0/program/libsddli.so
171 opt/openoffice.org/basis3.0/program/syssh.uno.so
173 opt/openoffice.org/ure/lib/javaloader.uno.so
175 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/unicodedata.so
182 opt/openoffice.org/basis3.0/program/ucpexpand1.uno.so
185 opt/openoffice.org/basis3.0/program/libmozabli.so
187 opt/openoffice.org/basis3.0/program/libxmlfdli.so
188 opt/openoffice.org/ure/lib/invocadapt.uno.so
189 opt/openoffice.org/ure/lib/proxyfac.uno.so
191 opt/openoffice.org/basis3.0/program/libscdli.so
198 opt/openoffice.org/basis3.0/program/canvasfactory.uno.so
199 opt/openoffice.org/basis3.0/program/behelper.uno.so
199 opt/openoffice.org/basis3.0/program/libsimplecmli.so
201 opt/openoffice.org/basis3.0/program/libodbcli.so
208 opt/openoffice.org/ure/lib/textoutstream.uno.so
210 opt/openoffice.org/basis3.0/program/libcommunili.so
212 opt/openoffice.org/basis3.0/program/libguesslangli.so
214 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/_bsddb.so
218 opt/openoffice.org/ure/lib/bridgefac.uno.so
220 opt/openoffice.org/basis3.0/program/components/libxpcom_compat_c.so
221 opt/openoffice.org/basis3.0/program/libidxli.so
221 opt/openoffice.org/ure/lib/libjuhx.so
227 opt/openoffice.org/basis3.0/program/libplacewareli.so
233 opt/openoffice.org/ure/lib/sunjavaplugin.so
237 opt/openoffice.org/basis3.0/program/liboffaccli.so
238 opt/openoffice.org/basis3.0/program/libxmxli.so
240 opt/openoffice.org/basis3.0/program/libepsli.so
241 opt/openoffice.org/ure/lib/textinstream.uno.so
242 opt/openoffice.org/basis3.0/program/libkab1.so
242 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/operator.so
245 opt/openoffice.org/basis3.0/program/components/libprofile.so
245 opt/openoffice.org/basis3.0/program/libmcnttype.so
246 opt/openoffice.org/basis3.0/program/libprotocolhandlerli.so
249 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/termios.so
251 opt/openoffice.org/basis3.0/program/libsmime3.so
252 opt/openoffice.org/basis3.0/program/localebe1.uno.so
253 opt/openoffice.org/basis3.0/program/sysmgr1.uno.so
257 opt/openoffice.org/basis3.0/program/libbf_migratefilterli.so
262 opt/openoffice.org/basis3.0/program/libssl3.so
266 opt/openoffice.org/basis3.0/program/librecentfile.so
284 opt/openoffice.org/basis3.0/program/liboooimprovecoreli.so
284 opt/openoffice.org/basis3.0/program/libvclplug_kdeli.so
297 opt/openoffice.org/basis3.0/program/libsaxli.so
303 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/datetime.so
310 opt/openoffice.org/basis3.0/program/libbindetli.so
318 opt/openoffice.org/basis3.0/program/libxmlfali.so
323 opt/openoffice.org/basis3.0/program/libpyuno.so
323 opt/openoffice.org/basis3.0/program/libsolverli.so
337 opt/openoffice.org/basis3.0/program/libxsltfilterli.so
347 opt/openoffice.org/basis3.0/program/libdb-4.2.so
348 opt/openoffice.org/ure/lib/connector.uno.so
352 opt/openoffice.org/basis3.0/program/cmdmail.uno.so
354 opt/openoffice.org/basis3.0/program/gconfbe1.uno.so
356 opt/openoffice.org/ure/lib/acceptor.uno.so
357 opt/openoffice.org/basis3.0/program/libbasegfxli.so
361 opt/openoffice.org/basis3.0/program/libsdbc2.so
373 opt/openoffice.org/basis3.0/program/libfwlli.so
375 opt/openoffice.org/basis3.0/program/passwordcontainer.uno.so
376 opt/openoffice.org/basis3.0/program/libbf_wrapperli.so
386 opt/openoffice.org/basis3.0/program/libdeploymentmiscli.so
388 opt/openoffice.org/basis3.0/program/libupdchkli.so
389 opt/openoffice.org/basis3.0/program/kdebe1.uno.so
393 opt/openoffice.org/basis3.0/program/libt602filterli.so
394 opt/openoffice.org/basis3.0/program/libhelplinkerli.so
395 opt/openoffice.org/basis3.0/program/libevtatt.so
408 opt/openoffice.org/basis3.0/program/productregistration.uno.so
410 opt/openoffice.org/basis3.0/program/libunopkgapp.so
415 opt/openoffice.org/basis3.0/program/libsvgfilterli.so
419 opt/openoffice.org/basis3.0/program/components/libmozldap.so
419 opt/openoffice.org/basis3.0/program/librasqal.so.0.0.0
422 opt/openoffice.org/basis3.0/program/libhyphenli.so
429 opt/openoffice.org/basis3.0/program/libdateli.so
432 opt/openoffice.org/basis3.0/program/libxpcom_compat.so
438 opt/openoffice.org/basis3.0/program/libucppkg1.so
461 opt/openoffice.org/basis3.0/program/simplecanvas.uno.so
465 opt/openoffice.org/basis3.0/program/liblnthli.so
468 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/pyexpat.so
472 opt/openoffice.org/basis3.0/program/libresli.so
478 opt/openoffice.org/ure/lib/invocation.uno.so
493 opt/openoffice.org/basis3.0/program/libpreloadli.so
496 opt/openoffice.org/basis3.0/program/ucpgvfs1.uno.so
497 opt/openoffice.org/basis3.0/program/libraptor.so.1.1.0
499 opt/openoffice.org/basis3.0/program/migrationoo2.uno.so
502 opt/openoffice.org/basis3.0/program/libicule.so.40.0
502 opt/openoffice.org/basis3.0/program/libspellli.so
503 opt/openoffice.org/basis3.0/program/components/libpref.so
507 opt/openoffice.org/ure/lib/libstore.so.3
524 opt/openoffice.org/basis3.0/program/fastsax.uno.so
543 opt/openoffice.org/basis3.0/program/ldapbe2.uno.so
547 opt/openoffice.org/basis3.0/program/libfileacc.so
553 opt/openoffice.org/basis3.0/program/updatefeed.uno.so
557 opt/openoffice.org/basis3.0/program/libnspr4.so
571 opt/openoffice.org/basis3.0/program/liblpsolve55.so
574 opt/openoffice.org/basis3.0/program/libdbacfgli.so
586 opt/openoffice.org/basis3.0/program/libtvhlp1.so
590 opt/openoffice.org/ure/lib/javavm.uno.so
592 opt/openoffice.org/basis3.0/program/libforli.so
593 opt/openoffice.org/basis3.0/program/basprovli.uno.so
597 opt/openoffice.org/basis3.0/program/libsrtrs1.so
599 opt/openoffice.org/ure/lib/introspection.uno.so
615 opt/openoffice.org/basis3.0/program/libfwmli.so
623 opt/openoffice.org/basis3.0/program/hatchwindowfactory.uno.so
624 opt/openoffice.org/basis3.0/program/libvos3gcc3.so
627 opt/openoffice.org/basis3.0/program/libvclplug_svpli.so
630 opt/openoffice.org/basis3.0/program/libadabasuili.so
644 opt/openoffice.org/basis3.0/program/libscnli.so
664 opt/openoffice.org/basis3.0/program/libbasebmpli.so
681 opt/openoffice.org/basis3.0/program/libvclplug_gtkli.so
685 opt/openoffice.org/basis3.0/program/libfwili.so
687 opt/openoffice.org/basis3.0/program/dlgprovli.uno.so
697 opt/openoffice.org/basis3.0/program/libucphier1.so
713 opt/openoffice.org/basis3.0/program/libflashli.so
725 opt/openoffice.org/basis3.0/program/fsstorage.uno.so
752 opt/openoffice.org/basis3.0/program/libdbpool2.so
752 opt/openoffice.org/basis3.0/program/sax.uno.so
780 opt/openoffice.org/basis3.0/program/libempli.so
784 opt/openoffice.org/basis3.0/program/fps_gnome.uno.so
790 opt/openoffice.org/basis3.0/program/libtextconversiondlgsli.so
833 opt/openoffice.org/basis3.0/program/updchk.uno.so
837 opt/openoffice.org/basis3.0/program/libcanvastoolsli.so
843 opt/openoffice.org/basis3.0/program/libsdbtli.so
850 opt/openoffice.org/basis3.0/program/libgoli.so
880 opt/openoffice.org/basis3.0/program/svtmisc.uno.so
886 opt/openoffice.org/basis3.0/program/libscriptframe.so
902 opt/openoffice.org/basis3.0/program/liblogli.so
906 opt/openoffice.org/ure/lib/reflection.uno.so
925 opt/openoffice.org/basis3.0/program/libanalysisli.so
971 opt/openoffice.org/basis3.0/program/libsoftokn3.so
979 opt/openoffice.org/basis3.0/program/libpdffilterli.so
984 opt/openoffice.org/basis3.0/program/libemboleobj.so
999 opt/openoffice.org/basis3.0/program/libabpli.so
999 opt/openoffice.org/basis3.0/program/libnss3.so
1006 opt/openoffice.org/basis3.0/program/libtlli.so
1018 opt/openoffice.org/basis3.0/program/liblegacy_binfiltersli.so
1046 opt/openoffice.org/basis3.0/program/stocservices.uno.so
1046 opt/openoffice.org/ure/lib/stocservices.uno.so
1068 opt/openoffice.org/basis3.0/program/libavmediali.so
1076 opt/openoffice.org/basis3.0/program/libucpftp1.so
1134 opt/openoffice.org/basis3.0/program/components/librdf.so
1134 opt/openoffice.org/basis3.0/program/libunordfli.so
1139 opt/openoffice.org/basis3.0/program/libfilterconfig1.so
1179 opt/openoffice.org/basis3.0/program/libdtransX11li.so
1193 opt/openoffice.org/basis3.0/program/libdbaxmlli.so
1229 opt/openoffice.org/basis3.0/program/libdbmmli.so
1249 opt/openoffice.org/basis3.0/program/ucptdoc1.uno.so
1287 opt/openoffice.org/basis3.0/program/libforuili.so
1305 opt/openoffice.org/basis3.0/program/libcached1.so
1310 opt/openoffice.org/basis3.0/program/libsplli.so
1318 opt/openoffice.org/basis3.0/program/stringresourceli.uno.so
1362 opt/openoffice.org/basis3.0/program/libstsli.so
1363 opt/openoffice.org/basis3.0/program/libmozjs.so
1368 opt/openoffice.org/basis3.0/program/libucpchelp1.so
1381 opt/openoffice.org/basis3.0/program/components/libi18n.so
1400 opt/openoffice.org/basis3.0/program/libucb1.so
1435 opt/openoffice.org/basis3.0/program/libucpfile1.so
1447 opt/openoffice.org/basis3.0/program/libpspli.so
1483 opt/openoffice.org/basis3.0/program/libxstor.so
1484 opt/openoffice.org/ure/lib/streams.uno.so
1499 opt/openoffice.org/basis3.0/program/libmysqlli.so
1510 opt/openoffice.org/basis3.0/program/libchartviewli.so
1546 opt/openoffice.org/basis3.0/program/libembobj.so
1586 opt/openoffice.org/basis3.0/program/components/libpipnss.so
1589 opt/openoffice.org/basis3.0/program/libcppcanvasli.so
1644 opt/openoffice.org/basis3.0/program/libplli.so
1669 opt/openoffice.org/basis3.0/program/libsotli.so
1669 opt/openoffice.org/basis3.0/program/libxsltdlgli.so
1697 opt/openoffice.org/basis3.0/program/libhwp.so
1697 opt/openoffice.org/basis3.0/program/libsofficeapp.so
1699 opt/openoffice.org/ure/lib/libstlport_gcc.so
1717 opt/openoffice.org/basis3.0/program/libxofli.so
1721 opt/openoffice.org/basis3.0/program/libxsec_fw.so
1726 opt/openoffice.org/basis3.0/program/components/libmork.so
1798 opt/openoffice.org/basis3.0/program/libctlli.so
1806 opt/openoffice.org/ure/lib/libuno_cppuhelpergcc3.so.3
1820 opt/openoffice.org/basis3.0/program/libvclplug_genli.so
1828 opt/openoffice.org/basis3.0/program/libuuili.so
1837 opt/openoffice.org/basis3.0/program/fps_office.uno.so
1869 opt/openoffice.org/basis3.0/program/libmsgbaseutil.so
1926 opt/openoffice.org/basis3.0/program/libxsec_xmlsec.so
1941 opt/openoffice.org/basis3.0/program/libfweli.so
1960 opt/openoffice.org/basis3.0/program/libflatli.so
1995 opt/openoffice.org/basis3.0/program/libevoabli.so
1996 opt/openoffice.org/basis3.0/program/libcalcli.so
2010 opt/openoffice.org/basis3.0/program/libdbpli.so
2011 opt/openoffice.org/basis3.0/program/libxmlsecurity.so
2057 opt/openoffice.org/basis3.0/program/libucbhelper4gcc3.so
2062 opt/openoffice.org/basis3.0/program/components/libxpconnect.so
2064 opt/openoffice.org/basis3.0/program/libpackage2.so
2129 opt/openoffice.org/basis3.0/program/libhsqldb.so
2168 opt/openoffice.org/basis3.0/program/libanimcore.so
2276 opt/openoffice.org/basis3.0/program/components/libuconv.so
2311 opt/openoffice.org/basis3.0/program/libspali.so
2327 opt/openoffice.org/basis3.0/program/libmswordli.so
2408 opt/openoffice.org/basis3.0/program/deploymentguili.uno.so
2432 opt/openoffice.org/basis3.0/program/libdbaseli.so
2457 opt/openoffice.org/basis3.0/program/libbibli.so
2460 opt/openoffice.org/ure/lib/libstdc++.so.6
2694 opt/openoffice.org/basis3.0/program/libutlli.so
2865 opt/openoffice.org/basis3.0/program/libodbcbaseli.so
2928 opt/openoffice.org/basis3.0/program/libwpftli.so
3029 opt/openoffice.org/basis3.0/program/libbf_smli.so
3104 opt/openoffice.org/basis3.0/program/libxcrli.so
3198 opt/openoffice.org/ure/lib/libxml2.so.2
3233 opt/openoffice.org/basis3.0/program/libsvlli.so
3245 opt/openoffice.org/basis3.0/program/components/libaddrbook.so
3287 opt/openoffice.org/basis3.0/program/libkabdrv1.so
3337 opt/openoffice.org/basis3.0/program/liblngli.so
3357 opt/openoffice.org/basis3.0/program/libmozabdrvli.so
3432 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/_curses_panel.so
3445 opt/openoffice.org/basis3.0/program/libadabasli.so
3730 opt/openoffice.org/basis3.0/program/libjdbcli.so
3784 opt/openoffice.org/basis3.0/program/libicui18n.so.40.0
3821 opt/openoffice.org/basis3.0/program/libdrawinglayerli.so
3906 opt/openoffice.org/basis3.0/program/libfileli.so
3970 opt/openoffice.org/basis3.0/program/libsduili.so
4075 opt/openoffice.org/basis3.0/program/libpython2.3.so.1.0
4097 opt/openoffice.org/basis3.0/program/deploymentli.uno.so
4150 opt/openoffice.org/basis3.0/program/libicuuc.so.40.0
4302 opt/openoffice.org/basis3.0/program/libxpcom.so
4319 opt/openoffice.org/basis3.0/program/liblocaledata_es.so
4502 opt/openoffice.org/basis3.0/program/liblocaledata_en.so
4663 opt/openoffice.org/ure/lib/libuno_sal.so.3
4676 opt/openoffice.org/ure/lib/bootstrap.uno.so
4722 opt/openoffice.org/basis3.0/program/components/libnecko.so
4982 opt/openoffice.org/basis3.0/program/libbf_soli.so
5013 opt/openoffice.org/basis3.0/program/libcharttoolsli.so
5256 opt/openoffice.org/basis3.0/program/libsmli.so
5374 opt/openoffice.org/basis3.0/program/python-core-2.3.4/lib/lib-dynload/_curses.so
5540 opt/openoffice.org/basis3.0/program/libbf_sbli.so
5811 opt/openoffice.org/basis3.0/program/slideshow.uno.so
6012 opt/openoffice.org/basis3.0/program/libbf_schli.so
6353 opt/openoffice.org/basis3.0/program/vclcanvas.uno.so
6481 opt/openoffice.org/basis3.0/program/libunoxmlli.so
6551 opt/openoffice.org/basis3.0/program/libscuili.so
6667 opt/openoffice.org/basis3.0/program/libscfiltli.so
6725 opt/openoffice.org/basis3.0/program/libcomphelp4gcc3.so
6730 opt/openoffice.org/basis3.0/program/libbf_sdli.so
6982 opt/openoffice.org/basis3.0/program/libbf_svtli.so
7116 opt/openoffice.org/basis3.0/program/libdbtoolsli.so
7671 opt/openoffice.org/basis3.0/program/libbasctlli.so
8414 opt/openoffice.org/basis3.0/program/libchartmodelli.so
9782 opt/openoffice.org/basis3.0/program/libpcrli.so
10042 opt/openoffice.org/basis3.0/program/libsbli.so
10240 opt/openoffice.org/basis3.0/program/libucpdav1.so
11268 opt/openoffice.org/basis3.0/program/i18npool.uno.so
11559 opt/openoffice.org/basis3.0/program/libvclli.so
11657 opt/openoffice.org/basis3.0/program/libfwkli.so
11915 opt/openoffice.org/basis3.0/program/libaccli.so
11976 opt/openoffice.org/basis3.0/program/libbf_xoli.so
12568 opt/openoffice.org/basis3.0/program/libchartcontrollerli.so
13352 opt/openoffice.org/basis3.0/program/configmgr2.uno.so
14279 opt/openoffice.org/basis3.0/program/libbf_frmli.so
15504 opt/openoffice.org/basis3.0/program/libxoli.so
16083 opt/openoffice.org/basis3.0/program/libdbali.so
16440 opt/openoffice.org/basis3.0/program/libswuili.so
18793 opt/openoffice.org/basis3.0/program/libvbaobjli.uno.so
19218 opt/openoffice.org/basis3.0/program/libcuili.so
19950 opt/openoffice.org/basis3.0/program/libsfxli.so
21368 opt/openoffice.org/basis3.0/program/libbf_scli.so
24233 opt/openoffice.org/basis3.0/program/libsvtli.so
25860 opt/openoffice.org/basis3.0/program/libfrmli.so
26811 opt/openoffice.org/basis3.0/program/libbf_swli.so
27025 opt/openoffice.org/basis3.0/program/libdbuli.so
31017 opt/openoffice.org/basis3.0/program/liblocaledata_euro.so
31950 opt/openoffice.org/basis3.0/program/libooxli.so
32073 opt/openoffice.org/basis3.0/program/libbf_svxli.so
35190 opt/openoffice.org/basis3.0/program/liblocaledata_others.so
40816 opt/openoffice.org/basis3.0/program/libtkli.so
46714 opt/openoffice.org/basis3.0/program/libsdli.so
49694 opt/openoffice.org/basis3.0/program/libscli.so
61034 opt/openoffice.org/basis3.0/program/libwriterfilterli.so
61287 opt/openoffice.org/basis3.0/program/libswli.so
84341 opt/openoffice.org/basis3.0/program/libsvxli.so
</pre>

= Measurements =

Measurements are done on a Sun Ultra 20 with a recent (as of February 25, 2009) Debian Unstable i386. The OOo is a <code>sb107/DEV300/src.m41/instsetoo_native/unxlngi6.pro/OpenOffice/archive/install/en-US/OOo_3.0.0_090219_unxlngi6_install.tar.gz</code> (i.e., [http://eis.services.openoffice.org/EIS2/cws.ShowCWS?Path=DEV300%2Fsb107 CWS sb107] as based on <code>DEV300m41</code> with just a fix for [http://qa.openoffice.org/issues/show_bug.cgi?id=99519 Issue 99519] included), installed to <code>/sb-tree1/ooo-m107</code> with <code>UserInstallation=file:///sb-tree2/ooo-m107/.openoffice.org/3</code> in <code>/sb-tree1/ooo-m107/openoffice.org3/program/bootstraprc</code>, “Check for updates automatically” disabled, “I do not want to register” selected (both during first <code>soffice</code> start), and “No, I do not wish to participate” selected (during second <code>soffice</code> start); the working directory is <code>/sb-tree3</code>.

During <code>soffice.bin</code> start up, [http://svn.services.openoffice.org/ooo/tags/DEV300_m44/vcl/unx/source/fontmanager/fontconfig.cxx <code>vcl/unx/source/fontmanager/fontconfig.cxx</code>] l. 791 calls [http://fontconfig.org/fontconfig-devel/r2744.html <code>FcConfigAppFontAddDir</code>] three times (with existing directory <code>/opt/openoffice.org/basis3.2/share/fonts/truetype</code> and non-existing directories <code>/opt/openoffice.org3/program/../basis-link/share/fonts/type1</code> and <code>~/.openoffice.org/3/user/fonts</code>). Apparently, during the first <code>soffice</code> start those directories are actually accessed and data about them stored at <code>~/.fontconfig</code> (resulting in heavy use of the <code>freetype</code> dynamic library), while during subsequent starts the cached data is used.

== <code>time</code> ==

Just after system start up run
<pre>
$ cd /sb-tree3
$ time /sb-tree1/ooo-sb107/openoffice.org3/program/soffice -swriter # press Ctrl-Q as soon as the text cursor starts to blink
$ time /sb-tree1/ooo-sb107/openoffice.org3/program/soffice -swriter # press Ctrl-Q as soon as the text cursor starts to blink
$ time /sb-tree1/ooo-sb107/openoffice.org3/program/soffice -swriter # press Ctrl-Q as soon as the text cursor starts to blink
</pre>
to get one cold and two warm start-up (plus shut-down) times. Repeat three times. The average of the three cold start ups is
<pre>
real 0m11.584s
user 0m2.335s
sys 0m0.237s
</pre>
and the average of the six warm start ups is
<pre>
real 0m3.528s
user 0m2.069s
sys 0m0.173s
</pre>

== <code>strace</code> ==

Just after system start up run
<pre>
$ cd /sb-tree3
$ strace -ff -T -o ~/cold /sb-tree1/ooo-sb107/openoffice.org3/program/soffice -swriter # press Ctrl-Q as soon as the text cursor starts to blink
$ strace -ff -T -o ~/warma /sb-tree1/ooo-sb107/openoffice.org3/program/soffice -swriter # press Ctrl-Q as soon as the text cursor starts to blink
$ strace -ff -T -o ~/warmb /sb-tree1/ooo-sb107/openoffice.org3/program/soffice -swriter # press Ctrl-Q as soon as the text cursor starts to blink
</pre>
to get one cold and two warm start-up (plus shut-down) times. Repeat three times (<code>cold1</code>–<code>cold3</code>, <code>warm1a</code>–<code>warm3b</code>). Use
<pre>
$ for i in cold1.*; do sed "s/^/${i#cold1.} /" "$i"; done | strace-eval > cold1-all
</pre>
(and similarly for the other measurements) with the following <code>strace-eval</code> Haskell script
<source lang="haskell">
-- Makefile:
-- .PHONY: strace-eval
-- strace-eval:
-- ghc-6.10.1 --make -o $@ Main.hs
--
-- Group strace output system calls by files they operate on:
--
-- $ strace -T -o log1 soffice.bin && strace-eval < log1 > log2
--
-- or
--
-- $ strace -ff -T -o log1 soffice && \
-- for i in log1.*; do sed "s/^/${i#log1.} /" "$i"; done | strace-eval > log2

{-# LANGUAGE ScopedTypeVariables #-}

module Main (main) where

import Data.Map as M
import GHC.Exts (sortWith)
import Text.Regex.Posix ((=~))

main :: IO ()
main = do c <- getContents
let cs = lines c
let m = process M.empty M.empty cs
mapM_ displayFileData $ reverse $ sortWith (fst . snd) $ M.toList m

type FdMap = M.Map (String, Integer) String -- (pid, fd) -> filepath

type FileMap = M.Map FileSpec FileData

data FileSpec = File String
| Fd String Integer -- pid, fd
| Unknown deriving (Eq, Ord)

type FileData = (Integer, [String]) -- (time, [lines])

process :: FdMap -> FileMap -> [String] -> FileMap
process _ fm [] = fm
process fdm fm (c:cs) = process fdm' fm' cs
where (fdm', fm') = processOne fdm fm c

processOne :: FdMap -> FileMap -> String -> (FdMap, FileMap)
processOne fdm fm c = case splitLine c of
Just (pid, s, a, r, n) ->
(fdm', M.insertWith merge fs (n, [c]) fm)
where (fdm', fs) = parse fdm pid s a r
_ ->
(fdm, M.insertWith merge Unknown (0, [c]) fm)
where merge (n', cs') (n, cs) = (n + n', cs ++ cs')

splitLine :: String -> Maybe (String, String, String, String, Integer)
splitLine c = case pts of
[pid, s, a, r, n1, n2] ->
Just (pid, s, a, r, 1000000 * read n1 + read n2)
_ -> Nothing
where pts = c =~~~ "^([0-9]+)? *([0-9A-Z_a-z]+)\$(.*)\$ += (.+) <([0-9]+)\\.([0-9][0-9][0-9][0-9][0-9][0-9])>$"

parse :: FdMap -> String -> String -> String -> String -> (FdMap, FileSpec)
parse fdm pid "_llseek" a _ =
(fdm, case a' of [fd] -> findFile fdm pid $ read fd)
where a' = a =~~~ "^([0-9]+),"
parse fdm pid "accept" a r = case (a', r') of
(_, [fd]) -> (fdm, Fd pid $ read fd)
([fd], _) -> (fdm, findFile fdm pid $ read fd)
where a' = a =~~~ "^([0-9]+),"
r' = r =~~~ "^([0-9]+)$"
parse fdm pid "access" a _ = (fdm, case a' of { (f:_) -> File f; _ -> Unknown })
where a' = a =~~~ "^\"(([^\"\\]|\\\\.)*)\"" -- or "^NULL"
parse fdm pid "bind" a _ = (fdm, case a' of [fd] -> findFile fdm pid $ read fd)
where a' = a =~~~ "^([0-9]+),"
parse fdm pid "chdir" a _ = (fdm, case a' of (f:_) -> File f)
where a' = a =~~~ "^\"(([^\"\\]|\\\\.)*)\"$"
parse fdm pid "chmod" a _ = (fdm, case a' of (f:_) -> File f)
where a' = a =~~~ "^\"(([^\"\\]|\\\\.)*)\","
parse fdm pid "chown32" a _ = (fdm, case a' of (f:_) -> File f)
where a' = a =~~~ "^\"(([^\"\\]|\\\\.)*)\","
parse fdm pid "close" a r =
case (a', r') of
([fd], ["0"]) -> (M.delete (pid, read fd) fdm, findFile fdm pid $ read fd)
([fd], _) -> (fdm, findFile fdm pid $ read fd)
where a' = a =~~~ "^([0-9]+)$"
r' = r =~~~ "^([0-9]+)$"
parse fdm pid "connect" a _ =
(fdm, case a' of [fd] -> findFile fdm pid $ read fd)
where a' = a =~~~ "^([0-9]+),"
parse fdm pid "execve" a _ = (fdm, case a' of (f:_) -> File f)
where a' = a =~~~ "^\"(([^\"\\]|\\\\.)*)\""
parse fdm pid "fcntl64" a _ =
(fdm, case a' of [fd] -> findFile fdm pid $ read fd)
where a' = a =~~~ "^([0-9]+),"
parse fdm pid "fstat64" a _ =
(fdm, case a' of [fd] -> findFile fdm pid $ read fd)
where a' = a =~~~ "^([0-9]+),"
parse fdm pid "fsync" a _ = (fdm, case a' of [fd] -> findFile fdm pid $ read fd)
where a' = a =~~~ "^([0-9]+)$"
parse fdm pid "ftruncate" a _ =
(fdm, case a' of [fd] -> findFile fdm pid $ read fd)
where a' = a =~~~ "^([0-9]+),"
parse fdm pid "ftruncate64" a _ =
(fdm, case a' of [fd] -> findFile fdm pid $ read fd)
where a' = a =~~~ "^([0-9]+),"
parse fdm pid "getcwd" a _ = (fdm, case a' of { (f:_) -> File f; _ -> Unknown })
where a' = a =~~~ "^\"(([^\"\\]|\\\\.)*)\"" -- or "^NULL"
parse fdm pid "getdents64" a _ =
(fdm, case a' of [fd] -> findFile fdm pid $ read fd)
where a' = a =~~~ "^([0-9]+),"
parse fdm pid "getpeername" a _ =
(fdm, case a' of [fd] -> findFile fdm pid $ read fd)
where a' = a =~~~ "^([0-9]+),"
parse fdm pid "getsockname" a _ =
(fdm, case a' of [fd] -> findFile fdm pid $ read fd)
where a' = a =~~~ "^([0-9]+),"
parse fdm pid "ioctl" a _ = (fdm, case a' of [fd] -> findFile fdm pid $ read fd)
where a' = a =~~~ "^([0-9]+),"
parse fdm pid "link" a _ = (fdm, case a' of (f:_) -> File f)
where a' = a =~~~ "^\"(([^\"\\]|\\\\.)*)\""
parse fdm pid "listen" a _ =
(fdm, case a' of [fd] -> findFile fdm pid $ read fd)
where a' = a =~~~ "^([0-9]+),"
parse fdm pid "lseek" a _ = (fdm, case a' of [fd] -> findFile fdm pid $ read fd)
where a' = a =~~~ "^([0-9]+),"
parse fdm pid "lstat64" a _ = (fdm, case a' of (f:_) -> File f)
where a' = a =~~~ "^\"(([^\"\\]|\\\\.)*)\""
parse fdm pid "mkdir" a _ = (fdm, case a' of (f:_) -> File f)
where a' = a =~~~ "^\"(([^\"\\]|\\\\.)*)\""
parse fdm pid "mmap2" a _ =
(fdm,
case a' of ["-1"] -> Unknown
[fd] -> findFile fdm pid $ read fd
_ -> error a)
where a' = a =~~~ ", (-?[0-9]+), -?[0-9a-fx]+$"
parse fdm pid "old_mmap" a _ =
(fdm,
case a' of ["-1"] -> Unknown
[fd] -> findFile fdm pid $ read fd
_ -> error a)
where a' = a =~~~ ", (-?[0-9]+), -?[0-9a-fx]+$"
parse fdm pid "open" a r =
case (a', r') of
(f:_, [fd]) -> (M.insertWith (error ("not empty <"++pid++"/"++fd++", "++a++", "++r++">") . const) (pid, read fd) f
fdm,
File f)
(f:_, _) -> (fdm, File f)
where a' = a =~~~ "^\"(([^\"\\]|\\\\.)*)\""
r' = r =~~~ "^([0-9]+)$"
parse fdm pid "pipe" a r =
(fdm,
case (a', r) of ([fd, _], "0") -> findFile fdm pid $ read fd
_ -> Unknown)
where a' = a =~~~ "^\\[([0-9]+), ([0-9]+)\\]$"
parse fdm pid "poll" a _ =
(fdm, case a' of [fd] -> findFile fdm pid $ read fd) --TODO
where a' = a =~~~ "^\\[\\{fd=([0-9]+),"
parse fdm pid "pread64" a _ =
(fdm, case a' of [fd] -> findFile fdm pid $ read fd)
where a' = a =~~~ "^([0-9]+),"
parse fdm pid "pwrite64" a _ =
(fdm, case a' of [fd] -> findFile fdm pid $ read fd)
where a' = a =~~~ "^([0-9]+),"
parse fdm pid "read" a _ = (fdm, case a' of [fd] -> findFile fdm pid $ read fd)
where a' = a =~~~ "^([0-9]+),"
parse fdm pid "readlink" a _ = (fdm, case a' of (f:_) -> File f)
where a' = a =~~~ "^\"(([^\"\\]|\\\\.)*)\""
parse fdm pid "readv" a _ = (fdm, case a' of [fd] -> findFile fdm pid $ read fd)
where a' = a =~~~ "^([0-9]+),"
parse fdm pid "recv" a _ =
(fdm, case a' of [fd] -> findFile fdm pid $ read fd)
where a' = a =~~~ "^([0-9]+),"
parse fdm pid "recvmsg" a _ =
(fdm, case a' of [fd] -> findFile fdm pid $ read fd)
where a' = a =~~~ "^([0-9]+),"
parse fdm pid "rename" a _ = (fdm, case a' of (f:_) -> File f)
where a' = a =~~~ "^\"(([^\"\\]|\\\\.)*)\""
parse fdm pid "rmdir" a _ = (fdm, case a' of (f:_) -> File f)
where a' = a =~~~ "^\"(([^\"\\]|\\\\.)*)\""
parse fdm pid "send" a _ = (fdm, case a' of [fd] -> findFile fdm pid $ read fd)
where a' = a =~~~ "^([0-9]+),"
parse fdm pid "setsockopt" a _ =
(fdm, case a' of [fd] -> findFile fdm pid $ read fd)
where a' = a =~~~ "^([0-9]+),"
parse fdm pid "shutdown" a _ =
(fdm, case a' of [fd] -> findFile fdm pid $ read fd)
where a' = a =~~~ "^([0-9]+),"
parse fdm pid "socket" a r =
case r' of
[fd] -> (fdm, Fd pid $ read fd)
_ -> (fdm, Unknown)
where r' = r =~~~ "^([0-9]+)$"
parse fdm pid "stat64" a _ = (fdm, case a' of (f:_) -> File f)
where a' = a =~~~ "^\"(([^\"\\]|\\\\.)*)\""
parse fdm pid "unlink" a _ = (fdm, case a' of (f:_) -> File f)
where a' = a =~~~ "^\"(([^\"\\]|\\\\.)*)\""
parse fdm pid "utime" a _ = (fdm, case a' of (f:_) -> File f)
where a' = a =~~~ "^\"(([^\"\\]|\\\\.)*)\""
parse fdm pid "write" a _ = (fdm, case a' of [fd] -> findFile fdm pid $ read fd)
where a' = a =~~~ "^([0-9]+),"
parse fdm pid "writev" a _ =
(fdm, case a' of [fd] -> findFile fdm pid $ read fd)
where a' = a =~~~ "^([0-9]+),"
parse fdm pid _ _ _ = (fdm, Unknown)

(=~~~) :: String -> String -> [String]
a =~~~ b = c
where (_::String, _::String, _::String, c) = a =~ b

displayFileData :: (FileSpec, FileData) -> IO ()
displayFileData (_, (0, [])) = return ()
displayFileData (s, (n, cs)) = do
putStrLn $ showSpec s ++ ": " ++ show n ++ "mu"
mapM_ (putStrLn . (" " ++)) $ cs

showSpec :: FileSpec -> String
showSpec Unknown = "???"
showSpec (Fd pid fd) = (if pid == "" then "" else pid ++ "/") ++ show fd
showSpec (File f) = "\"" ++ f ++ "\""

findFile :: FdMap -> String -> Integer -> FileSpec
findFile fdm pid fd = case M.lookup (pid, fd) fdm of
Just f -> File f
Nothing -> Fd pid fd
</source>
to group system calls by the files or file descriptors they work on. The output is a list of blocks, sorted descending on time spent. Each block consists of a start line consisting of a file tag, a colon, a space, and an accumulated time, followed by one or more lines (pertaining to the given file tag) from the (combined, in the case of <code>strace -ff -o</code>) original <code>strace</code> output (in original order), each prefixed with a space. A file tag is either a filepath in double quotes, or a <code><var>pid</var>/<var>fd</var></code> combination of numeric <code><var>pid</var></code> and <code><var>fd</var></code> (for uses of file descriptors that cannot be associated with a filepath; the “<code><var>pid</var>/</code>” part is left out for <code>strace</code> calls without <code>-ff</code>), or <code>???</code> for all system calls that are not associated with a filepath or file descriptor at all. The accumulated time is the sum of the times given by <code>strace -T</code> for the individual lines, measured in microseconds.

For the measured times, take the following into account:
* The description of the <code>-O</code> option on the man page of <code>strace</code>(1) makes you assume that the given numbers are not too accurate.
* In multi-threaded scenarios, large times for certain system calls naturally need not imply delays in start up (if those delays are compensated for by other threads making progress).
* Similarly, in multi-process scenarios, large times for certain system calls naturally need not imply delays in start up either (if those delays are compensated for by other processes making progress; this is especially true for large times given for <code>wait</code>-family system calls that are accumulated under the <code>???</code> file tag).

The resulting measurements do exhibit some variance, but concentrating on the top listed files (i.e., filtering out mere file descriptors and <code>???</code>) across cold and warm starts does show trends:

* Accessing the four Berkeley DB files of the extension manager is costly due to <code>fsync</code> system calls. However, the costly <code>flush</code> calls are only made during OOo shut-down, not during start-up. Typical numbers are for example
<pre>
"/sb-tree2/ooo-sb107/.openoffice.org/3/user/uno_packages/cache/registry/com.sun.star.comp.deployment.configuration.PackageRegistryBackend/registered_packages.db": 167833mu
"/sb-tree1/ooo-sb107/openoffice.org3/program/../share/uno_packages/cache/uno_packages.db": 58392mu
"/sb-tree1/ooo-sb107/openoffice.org3/program/../share/uno_packages/cache/registry/com.sun.star.comp.deployment.configuration.PackageRegistryBackend/registered_packages.db": 49750mu
"/sb-tree2/ooo-sb107/.openoffice.org/3/user/uno_packages/cache/uno_packages.db": 41407mu
</pre>

* Accessing <code>images_tango.zip</code> is costly due to many small <code>read</code> system calls. Typical numbers are for example
<pre>
"/sb-tree1/ooo-sb107/openoffice.org3/program/../basis-link/share/config/images_tango.zip": 119944mu
</pre>
for cold start and
<pre>
"/sb-tree1/ooo-sb107/openoffice.org3/program/../basis-link/share/config/images_tango.zip": 18541mu
</pre>
for warm start.

* Accessing the directories of the OOo installation is costyl due to many repeated <code>stat</code>-family system calls. Typical numbers are for example
<pre>
"/sb-tree1": 21751mu
"/sb-tree1/ooo-sb107": 18782mu
"/sb-tree1/ooo-sb107/openoffice.org3": 9481mu
"/sb-tree1/ooo-sb107/openoffice.org3/basis-link": 2640mu
"/sb-tree1/ooo-sb107/openoffice.org3/program": 5238mu
"/sb-tree1/ooo-sb107/openoffice.org3/program/../basis-link/program": 29mu
</pre>
for cold start and
<pre>
"/sb-tree1": 22727mu
"/sb-tree1/ooo-sb107": 19496mu
"/sb-tree1/ooo-sb107/openoffice.org3": 9811mu
"/sb-tree1/ooo-sb107/openoffice.org3/basis-link": 2742mu
"/sb-tree1/ooo-sb107/openoffice.org3/program": 5413mu
"/sb-tree1/ooo-sb107/openoffice.org3/program/../basis-link/program": 15mu
</pre>
for warm start.

== <code>callgrind</code> ==

Run
<pre>
$ cp -a /sb-tree1 /sb-tree1f
$ unstr /cws/so-cwsserv02/sb107/DEV300/scr.m41 /cws/so-cwsserv02/sb107/DEV300/unxlngi6.pro/inc.m41 /sb-tree1f/ooo-sb107
</pre>
once to get an unstripped OOo installation, using the following <code>unstr</code> Haskell script:
<source lang="haskell">
-- Makefile:
-- .PHONY: unstr
-- unstr:
-- ghc-6.10.1 --make -o $@ Main.hs
--
-- Replace ELF objects in an OOo installation with unstripped ones from a build
-- tree:
--
-- $ unstr <build-tree-root> <solver-inc-dir> <installation-root>

module Main (main) where

import Control.Monad (filterM, foldM, join, zipWithM_)
import Data.List (isPrefixOf)
import Data.Map (Map, empty, foldWithKey, insertWith)
import qualified Data.Map (lookup)
import System.Directory (copyFile, doesFileExist, getDirectoryContents)
import System.Environment (getArgs)
import System.Exit (ExitCode(ExitSuccess))
import System.FilePath (combine, dropFileName, joinPath, takeFileName)
import System.Posix.Files (getSymbolicLinkStatus, isDirectory, isRegularFile)
import System.Process (readProcessWithExitCode)

filterSystemDirs :: [FilePath] -> [FilePath]
filterSystemDirs = filter (\f -> f /= "." && f /= "..")

data Entry = Copy FilePath -- source
| Link FilePath -- resolved target

type EntryMap = Map FilePath (Maybe Entry)

parseLog :: EntryMap -> FilePath -> IO EntryMap
parseLog m f = do c <- readFile f
return $ foldr (parse . words) m $ lines c
where parse ["COPY", o, d] m' = insert m' d $ Copy o
parse ["LINK", t, l] m' = insert m' l $ Link $
combine (dropFileName l) t
insert m f e = insertWith (const $ const Nothing) f (Just e) m

type FileMap = Map FilePath (Maybe FilePath)

resolve :: FilePath -> EntryMap -> FileMap
resolve srcDir em = foldWithKey resolve' empty em
where resolve' kf Nothing fm = fm
resolve' kf (Just (Copy f)) fm = insert fm kf f
resolve' kf (Just (Link f)) fm =
resolve' kf (join $ Data.Map.lookup f em) fm
insert fm kf f = insertWith (const $ const Nothing) (takeFileName kf)
(Just $ combine srcDir f) fm

findBin :: FilePath -> IO [FilePath]
findBin = findBin' []
where findBin' l f = do
s <- getSymbolicLinkStatus f
case (isDirectory s, isRegularFile s) of
(True, _) -> do dirs <- getDirectoryContents f
let files = map (combine f) $
filterSystemDirs dirs
foldM findBin' l files
(_, True) -> isBinary f >>= return . choose (f : l) l
where choose a b c = if c then a else b
_ -> return l

isBinary :: FilePath -> IO Bool
isBinary f = do (e, o, _) <-
readProcessWithExitCode "/usr/bin/file" ["-h", f] ""
return $ e == ExitSuccess && (f ++ ": ELF ") `isPrefixOf` o

findSource :: FileMap -> FilePath -> Maybe FilePath
findSource m f = join $ Data.Map.lookup (takeFileName f) m

execute :: Integer -> (FilePath, Maybe FilePath) -> IO Integer
execute n (f, Nothing) = do putStrLn $ "No (unambiguous) source for " ++ f
return n
execute n (f, Just f') = do copyFile f' f
return $ n + 1

main :: IO ()
main = do [srcDir, logDir, instDir] <- getArgs
dirs <- getDirectoryContents logDir
let files = map (\x -> joinPath [logDir, x, "deliver.log"]) $
filterSystemDirs dirs
files' <- filterM doesFileExist files
em <- foldM parseLog empty files'
bins <- findBin instDir
n <- foldM execute 0
(zip bins $ map (findSource $ resolve srcDir em) bins)
putStrLn $
show n ++ " file" ++ (if n == 1 then "" else "s") ++ " copied"
</source>

Just after system start up run
<pre>
$ cd /sb-tree3 && valgrind --tool=callgrind --compress-strings=no /sb-tree1f/ooo-sb107/openoffice3/program/soffice.bin -swriter # press Ctrl-Q as soon as the text cursor starts to blink
$ cd /sb-tree3 && valgrind --tool=callgrind --compress-strings=no /sb-tree1f/ooo-sb107/openoffice3/program/soffice.bin -swriter # press Ctrl-Q as soon as the text cursor starts to blink
$ cd /sb-tree3 && valgrind --tool=callgrind --compress-strings=no /sb-tree1f/ooo-sb107/openoffice3/program/soffice.bin -swriter # press Ctrl-Q as soon as the text cursor starts to blink
</pre>
to get one cold and two warm start-up (plus shut-down) measurements. The variance, even across cold and warm start ups, appears to be minimal.

Interesting first results, using grouping by ELF object in <code>kcachegrind</code>, are the instruction reads spent directly within the top scoring ELF objects:
{| border="1"
|-
! ELF object
! absolute instruction reads
! relative instruction reads
|-
| total ∑
| align="right" | 2,597,556,857
| align="right" | 100.00%
|-
| <code>libuno_sal.so.3</code>
| align="right" | 731,982,997
| align="right" | 28.18%
|-
| <code>ld-2.7.so</code>
| align="right" | 551,561,186
| align="right" | 21.23%
|-
| <code>libpthread-2.7.so</code>
| align="right" | 259,698,813
| align="right" | 10.00%
|-
| <code>libstore.so.3</code>
| align="right" | 165,350,190
| align="right" | 6.37%
|-
| <code>configmgr2.uno.so</code>
| align="right" | 161,273,959
| align="right" | 6.21%
|-
| <code>libc-2.7.so</code>
| align="right" | 132,961,163
| align="right" | 5.12%
|-
| <code>libuno_cppu.so.3</code>
| align="right" | 111,161,292
| align="right" | 4.28%
|-
| <code>libfontconfig.so.1.3.0</code>
| align="right" | 91,777,652
| align="right" | 3.53%
|-
| <code>libuno_cppuhelpergcc3.so.3</code>
| align="right" | 43,931,839
| align="right" | 1.69%
|-
| <code>libtlli.so</code>
| align="right" | 43,326,910
| align="right" | 1.67%
|-
| <code>libgcc_s.so.1</code>
| align="right" | 25,236,175
| align="right" | 0.97%
|-
| <code>libfilterconfig1.so</code>
| align="right" | 23,319,326
| align="right" | 0.90%
|}

== <code>LD_DEBUG</code> ==

Run
<source lang="bash">
cd /sb-tree3
LD_DEBUG=bindings LD_DEBUG_OUTPUT=~/lddebug /sb-tree1/opt/openoffice.org3/program/soffice -swriter
</source>
and from the generated <code>~/lddebug.<var>pid</var></code> files pick the one corresponding to <code>soffice.bin</code> (usually the largest one). Pass it through the below Haskell script to dress it up. This gives information about all the symbolic relocations actually done at start-up (plus shut-down). Note that this includes all symbolic relocations from the data segments (as they cannot be postponed until needed).
<source lang="haskell">
-- Makefile:
-- .PHONY: lddebug-eval
-- lddebug-eval:
-- ghc-6.10.1 --make -o $@ Main.hs
--
-- For every dynamic object, list:
-- number of symbol bindings made by that object to itself
-- number of symbol bindings made by that object to other objects
-- number of symbol bindings made by that object (sum of above two)
-- number of symbol bindings made by other objects to that object
-- (Descending) sorting by any of those four columns is controlled by -1, -2,
-- -3, or -4, respectively.
-- Listing the symbols belonging to the different columns is controlled by +1,
-- +2, or +4, respectively.
--
-- $ LD_DEBUG=bindings LD_DEBUG_OUTPUT=lddebug soffice.bin && \
-- lddebug-eval -3 +1 +2 < lddebug > lddebug-a

{-# LANGUAGE ScopedTypeVariables #-}

module Main (main) where

import Control.Monad (when)
import Data.List (sort, sortBy)
import qualified Data.Map as M
import System.Environment (getArgs)
import Text.Regex.Posix ((=~))

main :: IO ()
main = do
(so, lb) <- handleArgs
c <- getContents
let m = foldr process M.empty $ lines c
reportTotal m
mapM_ (report lb) $ sortObjs so $ M.toList m

newtype SortColumn = SortColumn Int
data ListBindings = ListBindings { listToSelf :: Bool, listToOther :: Bool,
listFromOther :: Bool }

handleArgs :: IO (SortColumn, ListBindings)
handleArgs =
return . foldl handleArg (SortColumn 0, ListBindings False False False)
=<< getArgs
where handleArg (_, lb) "-1" = (SortColumn 1, lb)
handleArg (_, lb) "-2" = (SortColumn 2, lb)
handleArg (_, lb) "-3" = (SortColumn 3, lb)
handleArg (_, lb) "-4" = (SortColumn 4, lb)
handleArg (so, ListBindings _ b2 b4) "+1" =
(so, ListBindings True b2 b4)
handleArg (so, ListBindings b1 _ b4) "+2" =
(so, ListBindings b1 True b4)
handleArg (so, ListBindings b1 b2 _) "+4" =
(so, ListBindings b1 b2 True)

data Binding = Binding FilePath String deriving (Eq, Ord)
instance Show Binding where show (Binding fp sym) = fp ++ " " ++ sym

data Bindings = Bindings { toSelf :: [String], toOther :: [Binding],
fromOther :: [Binding] }
type Map = M.Map FilePath Bindings

process :: String -> Map -> Map
process l m =
case l =~~~ "binding file ([^ ]+) (.* )?to ([^ :]+)( .*): .* `(.+)'" of
[f1, _, f2, _, s] -> add f1 updateTo $
if f1 == f2 then m else add f2 updateFrom m
where updateTo = if f1 == f2 then Bindings [s] [] []
else Bindings [] [Binding f2 s] []
updateFrom = Bindings [] [] [Binding f1 s]
add = M.insertWith (+:+)
Bindings x1 y1 z1 +:+ Bindings x2 y2 z2 =
Bindings (x1 +::+ x2) (y1 +::+ y2) (z1 +::+ z2)
[] +::+ xs = xs
[x] +::+ xs = x : xs
_ -> m

reportTotal :: Map -> IO ()
reportTotal m = putStrLn $ "Total " ++ show s1 ++ " " ++ show s2 ++ " " ++
show (s1 + s2) ++ " " ++ show s4
where (s1, s2, s4) = M.fold sum (0, 0, 0) m
sum (Bindings x y z) (a1, a2, a3) = (a1 + length x, a2 + length y,
a3 + length z)

report :: ListBindings -> (FilePath, Bindings) -> IO ()
report lb (f, c) = do
putStrLn $ f ++ " " ++ show (len toSelf) ++ " " ++ show (len toOther) ++
" " ++ show (len toSelf + len toOther) ++ " " ++
show (len fromOther)
when (listToSelf lb) $ mapM_ (putStrLn . (" >< " ++)) $ sort $ toSelf c
when (listToOther lb) $
mapM_ (putStrLn . (" -> " ++) . show) $ sort $ toOther c
when (listFromOther lb) $
mapM_ (putStrLn . (" <- " ++) . show) $ sort $ fromOther c
where len x = length $ x c

sortObjs :: SortColumn -> [(FilePath, Bindings)] -> [(FilePath, Bindings)]
sortObjs (SortColumn 0) = id
sortObjs (SortColumn 1) = sortBy (\(_, Bindings x _ _) (_, Bindings y _ _) -> compare (length y) (length x))
sortObjs (SortColumn 2) = sortBy (\(_, Bindings _ x _) (_, Bindings _ y _) ->
compare (length y) (length x))
sortObjs (SortColumn 3) = sortBy (\(_, Bindings x1 x2 _) (_, Bindings y1 y2 _) ->
compare (length y1 + length y2) (length x1 + length x2))
sortObjs (SortColumn 4) = sortBy (\(_, Bindings _ _ x) (_, Bindings _ _ y) ->
compare (length y) (length x))

(=~~~) :: String -> String -> [String]
a =~~~ b = c
where (_::String, _::String, _::String, c) = a =~ b
</source>

Note that <code>ld-linux.so.2</code> on the used machine sometimes garbles lines of <code>LD_DEBUG</code> output (maybe a multi-threading issue), so the data produced by the above Haskell script need not be totally accurate.

= Symbolic Linking =

[http://qa.openoffice.org/issues/show_bug.cgi?id=85679 Issue 85679] “Link with -Wl,-Bsymbolic-functions -Wl,--dynamic-list-cpp-new -Wl,--dynamic-list-cpp-typeinfo when supported” suggest a performance boost on Linux through symbolic linking. This requires a fairly recent GNU <code>ld</code>. Experimenting with combining the existing (GCC 3.4.1 based) Hamburg <code>unxlngi6.pro</code> tool chain with (latest, as of March 2009) <code>ld</code> 2.19.1 failed, so I set up an environment using GNU binutils 2.19.1 and GNU GCC 4.3.3 (again, latest as of March 2009) on <code>v20z-so3</code> (see above).

* Build the new tool chain with <code>~/newgcc.sh ~/newgcc && rm -rf build</code>, where <code>~/newgcc.sh</code> is
<source lang="bash">
#!/bin/bash
set -e

mkdir ${1?}
mkdir build
cd build

wget http://ftp.gnu.org/gnu/binutils/binutils-2.19.1.tar.bz2
tar xfj binutils-2.19.1.tar.bz2
mkdir binutils-build
(cd binutils-build; \
../binutils-2.19.1/configure --prefix=${1?}; \
make; make install)

wget http://ftp.gnu.org/gnu/gmp/gmp-4.2.4.tar.bz2
tar xfj gmp-4.2.4.tar.bz2

wget http://www.mpfr.org/mpfr-2.4.1/mpfr-2.4.1.tar.bz2
tar xfj mpfr-2.4.1.tar.bz2
wget http://www.mpfr.org/mpfr-2.4.1/patches
(cd mpfr-2.4.1; patch -N -Z -p1 < ../patches)

wget http://ftp.gnu.org/gnu/gcc/gcc-4.3.3/gcc-4.3.3.tar.bz2
tar xfj gcc-4.3.3.tar.bz2
ln -s ../gmp-4.2.4 gcc-4.3.3/gmp
ln -s ../mpfr-2.4.1 gcc-4.3.3/mpfr
mkdir gcc-build
(cd gcc-build; \
export PATH=${1?}${PATH+:$PATH}; \
../gcc-4.3.3/configure --prefix=${1?} --enable-languages=c,c++; \
make; make install)
</source>

* Again using [http://eis.services.openoffice.org/EIS2/cws.ShowCWS?Path=DEV300%2Fsb107 CWS sb107] (see above), by now based on <code>DEV300m42</code>, replace the (Hamburg-internal) compiler-support libraries at <code>$SRC_ROOT/so_prereq/baseline/unxlngi6</code> (<code>libgcc_s.so.1</code>, <code>libstdc++.a</code>, <code>libstdc++.la</code>, <code>libstdc++.so.6.0.1</code>) with the ones from the new tool chain (<code>libgcc_s.so.1</code>, <code>libstdc++.a</code>, <code>libstdc++.la</code>, <code>libstdc++.so.6.0.10</code>) and in <code>$SRC_ROOT/solenv/bin/rpm-wrapper</code> replace “<code>${COMPATH?}</code>” with “<code>/so/env/gcc_3.4.1_p_linux_libc2.24</code>”.

* Merge in the relevant changes from [http://qa.openoffice.org/issues/show_bug.cgi?id=85679 Issue 85679] to support <code>HAVE_LD_BSYMBOLIC_FUNCTIONS</code> (ignoring the configure changes that are not relevant for a <code>setsolar</code> environment):
<source lang="bash">
cd $SOURCE_ROOT/DEV300/ooo && svn merge --ignore-ancestry svn://svn.services.openoffice.org/ooo/cws/buildporting31b -r 264159:264162
</source>

* Remove “<code>SO:b_server</code>” from <code>$SRC_ROOT/top/prj/build.lst</code>, to avoid an error later on when building (irrelevant, for OOo installation sets) <code>$SRC_ROOT/soldep/bootstrp</code>.

* Unfortunately, I did not manage to combine the standard Hamburg build environment (setting a specific <code>sysbaseroot</code>) with the new toolchain, so had to go with a null <code>sysbaseroot</code> (i.e., using stuff directly from the <code>v20z-so3</code> build machine). This means that results might be slightly different between the vanilla reference build and the builds checking the effects of symbolic linking.

* I did three builds:

** Build <var>N</var> using just the new tool chain (<code>EXTERNAL_WARNINGS_NOT_ERRORS=TRUE</code> is necessary as OOo is not yet completely warning-free for GCC 4.3.3):
<source lang="bash">
SYSBASE_ROOT= setcws -pro sb107 -- -compath ~/newgcc -sysbaseroot
cd $SRC_ROOT/finalize && EXTERNAL_WARNINGS_NOT_ERRORS=TRUE build --all
</source>

** Build <var>S</var> actually enabling symbolic linking:
<source lang="bash">
SYSBASE_ROOT= setcws -pro sb107 -- -compath ~/newgcc -sysbaseroot
cd $SRC_ROOT/finalize && EXTERNAL_WARNINGS_NOT_ERRORS=TRUE HAVE_LD_BSYMBOLIC_FUNCTIONS=TRUE build --all
</source>

** Build <var>F</var> using full symbolic linking (for functions and data) instead of symbolic linking for functions only, see [http://qa.openoffice.org/issues/show_bug.cgi?id=85679#desc7 issue 85679 additional comment 7]. For that, I changed from “<code>-Wl,-Bsymbolic-functions</code>” to “<code>-Wl,-Bsymbolic</code>” in <code>$SRC_ROOT/solenv/inc/unxlngi6.mk</code> (and forgot to adapt <code>$SRC_ROOT/icu/makefile.mk</code> and <code>$SRC_ROOT/stlport/makefile.mk</code> accordingly, which, however, should only have a minor effect on the resulting numbers).
<source lang="bash">
SYSBASE_ROOT= setcws -pro sb107 -- -compath ~/newgcc -sysbaseroot
cd $SRC_ROOT/finalize && EXTERNAL_WARNINGS_NOT_ERRORS=TRUE HAVE_LD_BSYMBOLIC_FUNCTIONS=TRUE build --all
</source>

This gave me four OOo installation sets (the original <var>O</var> one built with the standard Hamburg build environment, and the three new <var>N</var>, <var>S</var>, and <var>F</var> ones), which were measured on the dedicated machine (see above).

The <code>time</code> numbers (in each case, the average of three cold and six warm starts):
{| border="1"
|-
!
!
! <var>O</var>
! <var>N</var>
! <var>S</var>
! <var>F</var>
|-
! rowspan="3" | cold
! real
| align="right" | 11.16s
| align="right" | 9.48s
| align="right" | 10.53s
| align="right" | 9.54s
|-
! user
| align="right" | 2.09s
| align="right" | 1.91s
| align="right" | 1.71s
| align="right" | 1.69s
|-
! sys
| align="right" | 0.25s
| align="right" | 0.24s
| align="right" | 0.26s
| align="right" | 0.26s
|-
! rowspan="3" | warm
! real
| align="right" | 3.17s
| align="right" | 3.02s
| align="right" | 2.83s
| align="right" | 2.70s
|-
! user
| align="right" | 2.02s
| align="right" | 1.68s
| align="right" | 1.48s
| align="right" | 1.41s
|-
! sys
| align="right" | 0.16s
| align="right" | 0.15s
| align="right" | 0.14s
| align="right" | 0.15s
|}
Remarks:
* The <var>N</var> cold-start real time looks somewhat too small (probably due to the overall small number of measurements taken).
* The user times decrease as expected (as time spent in the run-time loader decreases).

The <code>callgrind</code> numbers (in each case, the second warm start in a row):
{| border="1"
|-
! colspan="3" | <var>O</var>
! colspan="3" | <var>N</var>
! colspan="3" | <var>S</var>
! colspan="3" | <var>F</var>
|-
| ∑
| align="right" | 2,283,122,716
| align="right" | 100.00%
| ∑
| align="right" | 2,334,805,645
| align="right" | 100.00%
| ∑
| align="right" | 2,038,552,787
| align="right" | 100.00%
| ∑
| align="right" | 2,003,854,857
| align="right" | 100.00%
|-
| <code>sal</code>
| align="right" | 647,373,539
| align="right" | 28.35%
| <code>sal</code>
| align="right" | 691,393,484
| align="right" | 29,61%
| <code>sal</code>
| align="right" | 634,256,193
| align="right" | 31.11%
| <code>sal</code>
| align="right" | 634,307,373
| align="right" | 31.65%
|-
| <code>ld</code>
| align="right" | 553,872,166
| align="right" | 24.26%
| <code>ld</code>
| align="right" | 546,564,974
| align="right" | 23.41%
| <code>ld</code>
| align="right" | 305,756,844
| align="right" | 15.00%
| <code>ld</code>
| align="right" | 271,385,866
| align="right" | 13.54%
|-
| <code>pthread</code>
| align="right" | 201,802,573
| align="right" | 8.84%
| <code>pthread</code>
| align="right" | 201,363,821
| align="right" | 8.62%
| <code>pthread</code>
| align="right" | 204,557,648
| align="right" | 10.03%
| <code>pthread</code>
| align="right" | 204,573,303
| align="right" | 10.21%
|-
| <code>configmgr</code>
| align="right" | 161,661,066
| align="right" | 7.08%
| <code>configmgr</code>
| align="right" | 180,214,766
| align="right" | 7.72%
| <code>configmgr</code>
| align="right" | 180,278,175
| align="right" | 8.84%
| <code>configmgr</code>
| align="right" | 180,278,731
| align="right" | 9.00%
|-
| <code>c</code>
| align="right" | 121,552,893
| align="right" | 5.32%
| <code>c</code>
| align="right" | 111,557,687
| align="right" | 4.78%
| <code>c</code>
| align="right" | 109,967,449
| align="right" | 5.39%
| <code>c</code>
| align="right" | 109,791,414
| align="right" | 5.48%
|-
| <code>cppu</code>
| align="right" | 111,123,581
| align="right" | 4.87%
| <code>cppu</code>
| align="right" | 99,323,254
| align="right" | 4.25%
| <code>cppu</code>
| align="right" | 99,387,817
| align="right" | 4.88%
| <code>cppu</code>
| align="right" | 99,377,448
| align="right" | 4.96%
|-
| <code>fontconfig</code>
| align="right" | 62,609,949
| align="right" | 2.74%
| <code>fontconfig</code>
| align="right" | 62,704,639
| align="right" | 2.69%
| <code>fontconfig</code>
| align="right" | 62,592,873
| align="right" | 3.07%
| <code>fontconfig</code>
| align="right" | 62,423,589
| align="right" | 3.12%
|-
| <code>cppuhelper</code>
| align="right" | 43,994,951
| align="right" | 1.93%
| <code>store</code>
| align="right" | 56,053,961
| align="right" | 2.40%
| <code>store</code>
| align="right" | 56,053,990
| align="right" | 2.75%
| <code>store</code>
| align="right" | 56,053,990
| align="right" | 2.80%
|-
| <code>tl</code>
| align="right" | 43,389,333
| align="right" | 1.90%
| <code>cppuhelper</code>
| align="right" | 49,022,128
| align="right" | 2.10%
| <code>cppuhelper</code>
| align="right" | 49,146,109
| align="right" | 2.41%
| <code>cppuhelper</code>
| align="right" | 49,096,875
| align="right" | 2.45%
|-
| <code>store</code>
| align="right" | 39,787,117
| align="right" | 1.74%
| <code>tl</code>
| align="right" | 40,778,608
| align="right" | 1.75%
| <code>tl</code>
| align="right" | 40,778,745
| align="right" | 2.00%
| <code>tl</code>
| align="right" | 40,778,944
| align="right" | 2.04%
|-
| <code>comphelp</code>
| align="right" | 27,750,228
| align="right" | 1.22%
| <code>comphelp</code>
| align="right" | 25,798,266
| align="right" | 1.10%
| <code>comphelp</code>
| align="right" | 25,797,960
| align="right" | 1.27%
| <code>comphelp</code>
| align="right" | 25,797,960
| align="right" | 1.29%
|-
| <code>gcc_s</code>
| align="right" | 24,964,856
| align="right" | 1.09%
| <code>filterconfig</code>
| align="right" | 23,233,003
| align="right" | 1.00%
| <code>filterconfig</code>
| align="right" | 23,233,003
| align="right" | 1.14%
| <code>filterconfig</code>
| align="right" | 23,233,003
| align="right" | 1.16%
|-
| align="center" | …
| align="center" | …
| align="center" | …
| align="center" | …
| align="center" | …
| align="center" | …
| align="center" | …
| align="center" | …
| align="center" | …
| align="center" | …
| align="center" | …
| align="center" | …
|}
Remarks:
* <code>callgrind</code>-instrumented runs of the various OOo instances often terminated with unexpected C++ exceptions, see [http://www.openoffice.org/issues/show_bug.cgi?id=100159 issue 100159] “unexpected exception from oooimprovement during shut down”. I could not get good runs for neither <var>O</var> nor <var>N</var>, so used ones crashing with <code>com::sun::star::lang::DisposedException</code> there; I did get good runs for both <var>S</var> and <var>F</var>, though. This probably makes the numbers for <var>O</var> and <var>N</var> somewhat different from what they would correctly be.
* Overall numbers apparently dropped from <code>DEV300m41</code> (see [[#callgrind]] above) to <code>DEV300m42</code> (<var>O</var>), mostly in <code>sal</code>, <code>store</code>, and <code>fontconfig</code>.
* The number of instruction reads appears to be generally higher for the new tool chain. This need not imply higher execution times, however. It might be caused by padding <code>nop</code>s or choices of multiple simple (and in sum fast) instructions instead of fewer (and in sum slower) complex ones.
* Numbers decreased significantly for <code>gcc_s</code> with the new tool chain. This is probably due to better support for C++ exception handling.
* As expected, for <code>ld</code> numbers decreased significantly from <var>N</var> to <var>S</var>, and then yet some more from <var>S</var> to <var>F</var> (while numbers remained the same for all other objects).

The <code>LD_DEBUG</code> numbers:
{| border="1"
! Relocations
! <var>O</var>
! <var>N</var>
! <var>S</var>
! <var>F</var>
|-
! intra-object
| align="right" | 45,698
| align="right" | 44,480
| align="right" | 16,520
| align="right" | 11,623
|-
! inter-object
| align="right" | 22,927
| align="right" | 22,705
| align="right" | 22,547
| align="right" | 22,270
|-
! ∑
| align="right" | 68,625
| align="right" | 67,185
| align="right" | 39,067
| align="right" | 33,893
|}
Remarks:
* As expected, intra-object numbers go down while inter-object numbers stay almost the same.

Using <code>-Bsymbolic</code> is in general unsound, however (and thus variant <var>F</var> subtly broken). If an executable references data from a shared library, the instance of data used at runtime will not be the instance in the shared library memory but a copy residing in the executable memory (using <code>R_386_COPY</code> relocation to copy data from the shared library memory to the executable memory). This will obviously fail if the shared library “short circuits” to use its own instance. (It might work if all executables were built as PIC, but it appears too fragile and cumbersome to enforce this, especially for all the third-party code built as part of OOo.) Therefore, other mechanisms need to be sought to reduce the number of intra-object (and inter-object!) references past the <var>S</var> numbers.

== <code>DEV300m44</code> ==

<code>DEV300m44</code> <code>unxlngi6.pro</code> is now routinely built with a new tool chain in the Hamburg <code>setsolar</code> environment, using GNU binutils 2.19 and GCC 4.2.3, which is close to the tool chain I used above. Below are measurements for five <code>unxlngi6.pro</code> OOo versions:
* <var>B</var> is the plain <code>OOO300m9</code> (i.e., OOo 3.0.0) version built by Hamburg Release Engineering (using the old tool chain based on GCC 3.4.1), for reference.
* <var>O</var> is the plain <code>DEV300m44</code> version built by Hamburg Release Engineering, using GCC 4.2.3 and binutils 2.19.
* <var>C</var> is a Hamburg <code>setsolar</code>-based build of CWS [http://eis.services.openoffice.org/EIS2/cws.ShowCWS?Path=DEV300%2Fsb107 CWS sb107] with fixes for [http://qa.openoffice.org/issues/show_bug.cgi?id=85679 issue 85679], [http://qa.openoffice.org/issues/show_bug.cgi?id=99519 issue 99519], [http://qa.openoffice.org/issues/show_bug.cgi?id=100348 issue 100348], [http://qa.openoffice.org/issues/show_bug.cgi?id=100396 issue 100396], and [http://qa.openoffice.org/issues/show_bug.cgi?id=100576 issue 100576] (and some additional issues that are not performance relevant), also using GCC 4.2.3 and binutils 2.19. Especially [http://qa.openoffice.org/issues/show_bug.cgi?id=100576 issue 100576] “enable HAVE_LD_HASH_STYLE in sdev300.ini” seems to make a difference.
* <var>N</var> is the same as <var>C</var>, but using my above tool chain (GCC 4.3.3 and binutils 2.19.1) instead—and again without the Hamburg <code>SYSBASE_ROOT</code> to be able to compile at all:
<source lang="bash">
SYSBASE_ROOT= setcws -pro sb107 -- -compath ~/newgcc -sysbaseroot
cd $SRC_ROOT/finalize && EXTERNAL_WARNINGS_NOT_ERRORS=TRUE build --all
</source>
* <var>F</var> is the same as <var>N</var>, only chainging <code>CFLAGSOPT=-Os -fno-strict-aliasing</code> to <code>CFLAGSOPT=-O3 -fno-strict-aliasing</code> in <code>solenv/inc/unxlngi6.mk</code> (and including a necessary fix for [http://qa.openoffice.org/issues/show_bug.cgi?id=100668 issue 100668] “explicit template instantiation: correct syntax”).

The <code>time</code> numbers (in each case, the average of three cold and six warm starts):
{| border="1"
|-
!
!
! <var>B</var>
! <var>O</var>
! <var>C</var>
! <var>C</var>′
! <var>N</var>
! <var>F</var>
! <var>F</var>′
! <var>F</var>′′
|-
! rowspan="4" | cold
! real
| align="right" | 10.39s
| align="right" | 10.04s
| align="right" | 8.29s
| align="right" | 6.91s
| align="right" | 8.54s
| align="right" | 9.56s
| align="right" | 7.63s
| align="right" | 11.08s
|-
! user
| align="right" | 2.03s
| align="right" | 2.05s
| align="right" | 1.59s
| align="right" | 1.42s
| align="right" | 1.53s
| align="right" | 1.47s
| align="right" | 1.19s
| align="right" | 1.55s
|-
! sys
| align="right" | 0.25s
| align="right" | 0.26s
| align="right" | 0.24s
| align="right" | 0.27s
| align="right" | 0.26s
| align="right" | 0.28s
| align="right" | 0.32s
| align="right" | 0.31s
|-
! pgflts
| align="right" | 542
| align="right" | 548
| align="right" | 549
| align="right" | 241
| align="right" | 550
| align="right" | 607
| align="right" | 241
| align="right" | 1007
|-
! rowspan="4" | warm
! real
| align="right" | 3.07s
| align="right" | 3.23s
| align="right" | 2.62s
| align="right" | 3.15s
| align="right" | 2.61s
| align="right" | 2.40s
| align="right" | 2.48s
| align="right" | 2.45s
|-
! user
| align="right" | 1.79s
| align="right" | 1.87s
| align="right" | 1.45s
| align="right" | 1.46s
| align="right" | 1.24s
| align="right" | 1.16s
| align="right" | 1.22s
| align="right" | 1.22s
|-
! sys
| align="right" | 0.15s
| align="right" | 0.16s
| align="right" | 0.16s
| align="right" | 0.18s
| align="right" | 0.18s
| align="right" | 0.17s
| align="right" | 0.19s
| align="right" | 0.14s
|-
! pgflts
| align="right" | 0
| align="right" | 7
| align="right" | 7
| align="right" | 7
| align="right" | 7
| align="right" | 7
| align="right" | 7
| align="right" | 7
|}
* <var>C</var>′ and <var>F</var>′ are like <var>C</var> resp. <var>F</var> but with [http://qa.openoffice.org/issues/show_bug.cgi?id=100884 issue 100884] fixed and <code>pagein-common</code> and <code>pagein-writer</code> modified to contain all libraries from the <code>OOo</code> installation that are loaded during start-up.
* <var>F</var>′′ is like <var>F</var> but with the call to <code>pagein</code> commented out in the <code>soffice</code> wrapper script.
* “pgflts” is the number of “major (requiring I/O) page faults” as reported by <code>/usr/bin/time -v</code>.

The <code>callgrind</code> numbers:
{| border="1"
|-
! colspan="3" | <var>B</var>
! colspan="3" | <var>O</var>
! colspan="3" | <var>C</var>
! colspan="3" | <var>N</var>
! colspan="3" | <var>F</var>
|-
| ∑
| align="right" | 2,343,921,428
| align="right" | 100.00%
| ∑
| align="right" | 2,480,626,988
| align="right" | 100.00%
| ∑
| align="right" | 2,154,221,636
| align="right" | 100.00%
| ∑
| align="right" | 1,941,254,692
| align="right" | 100.00%
| ∑
| align="right" | 1,784,892,501
| align="right" | 100.00%
|-
| <code>sal</code>
| align="right" | 613,760,471
| align="right" | 26.19%
| <code>sal</code>
| align="right" | 618,714,642
| align="right" | 24.94%
| <code>sal</code>
| align="right" | 618,363,619
| align="right" | 28.70%
| <code>sal</code>
| align="right" | 642,648,488
| align="right" | 33.10%
| <code>sal</code>
| align="right" | 583,727,656
| align="right" | 32.70%
|-
| <code>ld</code>
| align="right" | 520,524,128
| align="right" | 22.21%
| <code>ld</code>
| align="right" | 549,307,081
| align="right" | 22.14%
| <code>configmgr</code>
| align="right" | 267,645,553
| align="right" | 12.42%
| <code>ld</code>
| align="right" | 219,943,725
| align="right" | 11.33%
| <code>ld</code>
| align="right" | 219,918,343
| align="right" | 12.32%
|-
| <code>pthread</code>
| align="right" | 216,174,061
| align="right" | 9.22%
| <code>configmgr</code>
| align="right" | 267,677,829
| align="right" | 10.79%
| <code>ld</code>
| align="right" | 223,705,486
| align="right" | 10.38%
| <code>pthread</code>
| align="right" | 204,639,671
| align="right" | 10.54%
| <code>pthread</code>
| align="right" | 204,929,641
| align="right" | 11.48%
|-
| <code>configmgr</code>
| align="right" | 151,420,129
| align="right" | 6.46%
| <code>pthread</code>
| align="right" | 205,754,007
| align="right" | 8.29%
| <code>pthread</code>
| align="right" | 205,541,731
| align="right" | 9.54%
| <code>configmgr</code>
| align="right" | 180,332,775
| align="right" | 9.29%
| <code>configmgr</code>
| align="right" | 133,123,244
| align="right" | 7.46%
|-
| <code>c</code>
| align="right" | 136,653,675
| align="right" | 5.83%
| <code>c</code>
| align="right" | 115,297,223
| align="right" | 4.65%
| <code>c</code>
| align="right" | 115,251,998
| align="right" | 5.35%
| <code>c</code>
| align="right" | 110,134,686
| align="right" | 5.67%
| <code>c</code>
| align="right" | 110,172,575
| align="right" | 6.17%
|-
| <code>store</code>
| align="right" | 133,941,126
| align="right" | 5.71%
| <code>cppu</code>
| align="right" | 104,329,278
| align="right" | 4.21%
| <code>cppu</code>
| align="right" | 104,274,668
| align="right" | 4.84%
| <code>cppu</code>
| align="right" | 99,445,552
| align="right" | 5.12%
| <code>cppu</code>
| align="right" | 99,404,356
| align="right" | 5.57%
|-
| <code>cppu</code>
| align="right" | 101,645,154
| align="right" | 4.34%
| <code>cppuhelper</code>
| align="right" | 69,983,048
| align="right" | 2.82%
| <code>cppuhelper</code>
| align="right" | 69,869,741
| align="right" | 3.24%
| <code>fontconfig</code>
| align="right" | 62,572,767
| align="right" | 3.22%
| <code>fontconfig</code>
| align="right" | 62,470,938
| align="right" | 3.50%
|-
| <code>fontconfig</code>
| align="right" | 91,592,358
| align="right" | 3.91%
| <code>fontconfig</code>
| align="right" | 62,635,949
| align="right" | 2.53%
| <code>fontconfig</code>
| align="right" | 62,579,720
| align="right" | 2.90%
| <code>cppuhelper</code>
| align="right" | 49,302,429
| align="right" | 2.54%
| <code>tl</code>
| align="right" | 39,124,806
| align="right" | 2.19%
|-
| <code>tl</code>
| align="right" | 44,621,672
| align="right" | 1.90%
| <code>store</code>
| align="right" | 49,663,092
| align="right" | 2.00%
| <code>store</code>
| align="right" | 49,663,469
| align="right" | 2.31%
| <code>tl</code>
| align="right" | 40,230,939
| align="right" | 2.07%
| <code>cppuhelper</code>
| align="right" | 37,836,248
| align="right" | 2.12%
|-
| <code>cppuhelper</code>
| align="right" | 38,147,061
| align="right" | 1.63%
| <code>tl</code>
| align="right" | 46,338,109
| align="right" | 1.87%
| <code>tl</code>
| align="right" | 46,338,474
| align="right" | 2.15%
| <code>store</code>
| align="right" | 35,294,336
| align="right" | 1.82%
| <code>comphelp</code>
| align="right" | 28,243,242
| align="right" | 1.58%
|-
| <code>gcc_s</code>
| align="right" | 25,960,226
| align="right" | 1.11%
| <code>vcl</code>
| align="right" | 37,507,044
| align="right" | 1.51%
| <code>vcl</code>
| align="right" | 37,508,119
| align="right" | 1.74%
| <code>comphelp</code>
| align="right" | 25,799,196
| align="right" | 1.33%
| <code>store</code>
| align="right" | 27,574,934
| align="right" | 1.54%
|-
| align="center" | …
| align="center" | …
| align="center" | …
| align="center" | …
| align="center" | …
| align="center" | …
| align="center" | …
| align="center" | …
| align="center" | …
| align="center" | …
| align="center" | …
| align="center" | …
| align="center" | …
| align="center" | …
| align="center" | …
|}
* While the reductions from <var>O</var> to <var>C</var> are exactly as expected, the reductions from <var>C</var> to <var>N</var> seem over-optimistic (especially the extreme reduction for <code>cofnigmgr</code>). However, I could not find any mistakes (the set of dynamic libraries involved is exactly the same, high-level <code>callgrind</code> call numbers appear comparable). It appears that GCC 4.3.3 more aggressively inlines functions, which might explain some of the impact on C++ libraries that might contain lots of small functions (like <code>configmgr</code> or <code>cppuhelper</code>).

The <code>LD_DEBUG</code> numbers:
{| border="1"
! Relocations
! <var>B</var>
! <var>O</var>
! <var>C</var>
! <var>N</var>
! <var>F</var>
|-
! intra-object
| align="right" | 44,088
| align="right" | 45,226
| align="right" | 15,110
| align="right" | 14,793
| align="right" | 14,790
|-
! inter-object
| align="right" | 23,062
| align="right" | 22,825
| align="right" | 22,265
| align="right" | 22,162
| align="right" | 22,118
|-
! ∑
| align="right" | 67,150
| align="right" | 68,051
| align="right" | 37,375
| align="right" | 36,955
| align="right" | 36,908
|}
* The reductions from <var>C</var> to <var>N</var> appear to be due to
** inter-object resolutions of <code>_ZTI</code> and <code>_ZTS</code> (i.e., RTTI) symbols for types in anonymous namespaces being done directly rather than via symbol lookup;
** inter- and intra-object resolutions of truly vague <code>_ZTV</code> (i.e., vtable) symbols (i.e., belonging to types without key functions, see [http://www.codesourcery.com/public/cxx-abi/abi.html#vague Itanium C++ ABI]) being done directly (i.e., always intra-object) rather than via symbol lookup;
** to a small degree, calls to functions like <code>memcpy</code> being inlined instead of referring to <code>libc</code>.

[[Category:Performance]]

Playing with Window Toolkit AWT

2009-12-03T06:04:27Z

Newacct:

{{Documentation/NeedsRework}}
{{Documentation/Note|This chapter is old : written long before discovering the new Dialog for components in [[Documentation/DevGuide/WritingUNO/Accessing_Dialogs|Developer's Guide]]. At the moment I have only managed such [[Component_and_Dialog|Dialogs in components]] but I hope to work and see if it is not possible to use them in binaries executable.}}
==Danny Brewer's Explanations==
There are two different things here. Actually three.
# Dialogs
# AWT
# Forms

Forms are much higher level than the other two.

Of the first two, Dialogs are something using the UnoDialogControl and its model. You can also create AWT windows with controls.

AWT windows are modeless, and are not tied to any other window.

AWT windows are not the same thing as dialogs.

Generally, dialogs are operated modally by calling execute() on the dialog.

I have also had some success with operating dialogs modelessly. Just unhide the dialog, and it can be used modelessly. One drawback is that the modeless dialog seems to be tied to some concept of a "parent" window. I'm not sure, but I think that tends to be whatever window was in front when you created the dialog. So for example, you could create a modeless dialog that allows you to work with your document, but that modeless dialog's behavior appears to be tied to that document. Bring the modeless dialog to the front, and its document also comes to the front.

==The MessageBox Windows==
The starting code is roughly the same as previously (examples/DevelopersGuide/ProfUNO/CppBinding/). We examine also the “<OpenOffice.org1.1_SDK>/examples/DevelopersGuide/Components/Addons/ProtocolHandlerAddon_cpp” example where we find a MessageBox window. The corresponding code is given here (see also <idl>com.sun.star.awt.XWindowPeer</idl>, <idl>com.sun.star.awt.XMessageBox</idl>, <idl>com.sun.star.frame.XFrame</idl>, <idl>com.sun.star.awt.XToolkit</idl> interfaces and <idl>com.sun.star.awt.WindowDescriptor</idl> structure and <idl>com.sun.star.awt.WindowAttribute</idl> constants ) :
<source lang="cpp">
//Listing 1 MessageBox Windows (deprecated)
// C++
// Don't forget to add : #include <com/sun/star/awt/WindowDescriptor.hpp>
// Don't forget to add "com.sun.star.awt.WindowDescriptor \" in the makefile
// Don't forget to add : #include <com/sun/star/awt/WindowAttribute.hpp>
// Don't forget to add "com.sun.star.awt.WindowAttribute \" in the makefile
// Don't forget to add : #include <com/sun/star/awt/XWindowPeer.hpp>
// Don't forget to add "com.sun.star.awt.XWindowPeer \" in the makefile
// Don't forget to add : #include <com/sun/star/awt/XMessageBox.hpp>
// Don't forget to add "com.sun.star.awt.XMessageBox \" in the makefile

/**
* Show a message box with the UNO based toolkit
*/
static void ShowMessageBox( const Reference< XToolkit >& rToolkit,
const Reference< XFrame >& rFrame, const OUString& aTitle, const OUString& aMsgText )
{
if ( rFrame.is() && rToolkit.is() )
{
// describe window properties.
WindowDescriptor aDescriptor;
aDescriptor.Type = WindowClass_MODALTOP;
aDescriptor.WindowServiceName = OUString( RTL_CONSTASCII_USTRINGPARAM( "infobox" ));
aDescriptor.ParentIndex = -1;
aDescriptor.Parent = Reference< XWindowPeer >
( rFrame->getContainerWindow(), UNO_QUERY );
aDescriptor.Bounds = Rectangle(300,200,300,200);
aDescriptor.WindowAttributes = WindowAttribute::BORDER |
WindowAttribute::MOVEABLE | WindowAttribute::CLOSEABLE;

Reference< XWindowPeer > xPeer = rToolkit->createWindow( aDescriptor );
if ( xPeer.is() )
{
Reference< XMessageBox > xMsgBox( xPeer, UNO_QUERY );
if ( xMsgBox.is() )
{
xMsgBox->setCaptionText( aTitle );
xMsgBox->setMessageText( aMsgText );
xMsgBox->execute();
}
}
}
}
</source>

Similar script in [[Python|PyUNO]] from the Python Samples included in <openoffice.org version>/share/Scripts/python/MsgBox.py:
<source lang="python">
from com.sun.star.awt import Rectangle
from com.sun.star.awt import WindowDescriptor

from com.sun.star.awt.WindowClass import MODALTOP
from com.sun.star.awt.VclWindowPeerAttribute import OK, OK_CANCEL, YES_NO, YES_NO_CANCEL, \
RETRY_CANCEL, DEF_OK, DEF_CANCEL, DEF_RETRY, DEF_YES, DEF_NO

def TestMessageBox():
doc = XSCRIPTCONTEXT.getDocument()
parentwin = doc.CurrentController.Frame.ContainerWindow

s = "This is a test"
t = "Test"
res = MessageBox(parentwin, s, t, "querybox", YES_NO_CANCEL + DEF_NO)

s = res
MessageBox(parentwin, s, t, "infobox")

# Show a message box with the UNO based toolkit
def MessageBox(ParentWin, MsgText, MsgTitle, MsgType="messbox", MsgButtons=OK):

MsgType = MsgType.lower()

#available msg types
MsgTypes = ("messbox", "infobox", "errorbox", "warningbox", "querybox")

if MsgType not in MsgTypes:
MsgType = "messbox"

#describe window properties.
aDescriptor = WindowDescriptor()
aDescriptor.Type = MODALTOP
aDescriptor.WindowServiceName = MsgType
aDescriptor.ParentIndex = -1
aDescriptor.Parent = ParentWin
#aDescriptor.Bounds = Rectangle()
aDescriptor.WindowAttributes = MsgButtons

tk = ParentWin.getToolkit()
msgbox = tk.createWindow(aDescriptor)

msgbox.setMessageText(MsgText)
if MsgTitle :
msgbox.setCaptionText(MsgTitle)

return msgbox.execute()

g_exportedScripts = TestMessageBox,
</source>

To understand the WindowAttribute::BORDER and other constants, we first have a look at the IDL file “WindowAttribute.idl” describing the windows' attributes (<idl>com.sun.star.awt.WindowAttribute</idl>) :
<source lang="idl">
//Listing 2 WindowAttribute IDL File
// IDL
module com { module sun { module star { module awt {
constants WindowAttribute
{
const long SHOW = 1;
const long FULLSIZE = 2;
const long OPTIMUMSIZE = 4;
const long MINSIZE = 8;
const long BORDER = 16;
const long SIZEABLE = 32;
const long MOVEABLE = 64;
const long CLOSEABLE = 128;
const long SYSTEMDEPENDENT = 256;
};
}; }; }; };
</source>
We have a look at <idl>com.sun.star.awt.XMessageBox</idl> IDL file :
<source lang="idl">
//Listing 3 XMessageBox Interface : IDL File
// IDL
module com { module sun { module star { module awt {
/** gives access to a message box.
@deprecated
*/
interface XMessageBox: com::sun::star::uno::XInterface
{
[oneway] void setCaptionText( [in] string aText );
string getCaptionText();
[oneway] void setMessageText( [in] string aText );
string getMessageText();
short execute();
};
}; }; }; };
</source>
where we learn this interface is deprecated.
We give now a complete main in a listing to learn how to use the previous ShowMessageBox procedure :
<source lang="cpp">
//Listing 4 Complete Program showing a Message Box Window
//C++
int main( ) {
//retrieve an instance of the remote service manager
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();
if( rOfficeServiceManager.is() ){
printf( "Connected sucessfully to the office\n" );
}

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
if( rComponentLoader.is() ){
printf( "XComponentloader successfully instanciated\n" );
}
// Don't forget to add : #include <com/sun/star/awt/XToolkit.hpp>
// Don't forget to add "com.sun.star.awt.XToolkit \" in the makefile
// Query the XTollkit Interface
Reference< XToolkit >rToolkit = Reference< XToolkit >
( rOfficeServiceManager->createInstance(
OUString( RTL_CONSTASCII_USTRINGPARAM(
"com.sun.star.awt.Toolkit" ))), UNO_QUERY );

if (rToolkit.is()) {
printf ("OK...\n");
} else printf("Toolkit Error\n");

Reference< XDesktop > rDesktop(Desktop,UNO_QUERY);
Reference< XFrame > rFrame=rDesktop->getCurrentFrame();
if (rFrame.is()) printf("rFrame ... OK\n"); else printf("rFrame Error\n");

ShowMessageBox( rToolkit, rFrame,OUString::createFromAscii("Hello") ,
OUString::createFromAscii("Your First Message\n OK ?") );

return 0;
}
</source>
(See also <idl>com.sun.star.awt.XToolkit</idl> interface and <idl>com.sun.star.awt.Toolkit</idl> service).
We can draw three important things from this code :
*the way we can use such an IDL file (given above) [[SDKCppLanguage#To_go_further_:_the_Constant_Type_Problem|with constants in C++]] : it's not the first time we encounter this kind of IDL file,
*the way we can access an interface through a service with a createInstance and UNO_QUERY simultaneously (see how do we obtain rToolkit)
*we see also how we obtain a frame from a <idl>com.sun.star.frame.Desktop</idl> service.
We will present later a Desktop Helper using this message box code. (See [[Constructing_Helpers#Desktop_Helper_with_message_box|here]])

==A very simple Window==
We give now a listing to construct a very simple windows using UNO toolkit (See also <idl>com.sun.star.awt.XToolkit</idl> , <idl>com.sun.star.frame.XFrame</idl> and <idl>com.sun.star.frame.XDesktop</idl> interfaces) :
<source lang="cpp">
//Listing 5 Constructing a simple Window
// C++
main( ) {
Reference< XMultiServiceFactory > rOfficeServiceManager;
rOfficeServiceManager = ooConnect();

if( rOfficeServiceManager.is() ){
printf( "Connected sucessfully to the office\n" );
}

//get the desktop service using createInstance returns an XInterface type
Reference< XInterface > Desktop = rOfficeServiceManager->createInstance(
OUString::createFromAscii( "com.sun.star.frame.Desktop" ));

//query for the XComponentLoader interface
Reference< XComponentLoader > rComponentLoader (Desktop, UNO_QUERY);
if( rComponentLoader.is() ){
printf( "XComponentloader successfully instanciated\n" );

}

// Don't forget to add : #include <com/sun/star/awt/XToolkit.hpp>
// Don't forget to add "com.sun.star.awt.XToolkit \" in the makefile
// Query the XTollkit Interface
Reference< XToolkit >rToolkit = Reference< XToolkit >( rOfficeServiceManager->createInstance(
OUString( RTL_CONSTASCII_USTRINGPARAM(
"com.sun.star.awt.Toolkit" ))), UNO_QUERY );

if (rToolkit.is()) {
printf ("OK...\n");
} else printf("Toolkit Error\n");

Reference< XDesktop > rDesktop(Desktop,UNO_QUERY);

// *** essai fenetre
if ( rToolkit.is() )
{
// describe window properties.
WindowDescriptor aDescriptor;
aDescriptor.Type = WindowClass_TOP;
aDescriptor.WindowServiceName = OUString( RTL_CONSTASCII_USTRINGPARAM(""));
aDescriptor.ParentIndex = -1;
aDescriptor.Parent = rToolkit->getDesktopWindow();
aDescriptor.Bounds = Rectangle(100,200,300,400);
aDescriptor.WindowAttributes = WindowAttribute::BORDER | WindowAttribute::MOVEABLE | WindowAttribute::SHOW | WindowAttribute::CLOSEABLE
| WindowAttribute::SIZEABLE;
Reference< XWindowPeer > xWindowPeer = rToolkit->createWindow( aDescriptor );
Reference< XWindow > xWindow(xWindowPeer,UNO_QUERY);
xWindowPeer->setBackground(0xFF00FF);

// At this point, if you stop the program, you will have a new OOo window on the screen,
//but you cannot do anything with it. You cannot even close it!
// create a new frame
Reference< XFrame > xFrame =Reference< XFrame >( rOfficeServiceManager->createInstance(
OUString( RTL_CONSTASCII_USTRINGPARAM(
"com.sun.star.frame.Frame" ))), UNO_QUERY );
xFrame->initialize(xWindow);
Reference < XFramesSupplier > xFramesSupplier(Desktop,UNO_QUERY);
xFrame->setCreator(xFramesSupplier);
xFrame->setName(OUString::createFromAscii("Window 1"));
getchar();
}
return 0;
}
</source>

==The file picker dialog==
We want provide a dialog box for searching a file and returning its name. We start from a Bernard Marcelly's book example. When working with file picker dialog, we are concerned with three IDL files. Here is the first one (<idl>com.sun.star.ui.dialogs.XFilePicker</idl>) :
<source lang="idl">
//Listing 6 XFilePicker Interface : IDL File
// IDL
module com { module sun { module star { module ui { module dialogs {
interface XFilePicker: com::sun::star::ui::dialogs::XExecutableDialog
{
void setMultiSelectionMode( [in] boolean bMode );
void setDefaultName( [in] string aName );
void setDisplayDirectory( [in] string aDirectory )
raises( ::com::sun::star::lang::IllegalArgumentException );
string getDisplayDirectory();
sequence< string > getFiles();
};
}; }; }; }; };
</source>
The beginning of this file indicates we are concerned with <idl>com.sun.star.ui.dialogs.XExecutableDialog</idl> too because of inheritance :
<source lang="idl">
//Listing 7 XExecutableDialog Interface : IDL File
// IDL
module com { module sun { module star { module ui { module dialogs {
interface XExecutableDialog: com::sun::star::uno::XInterface
{
void setTitle( [in] string aTitle );
short execute();
};
}; }; }; }; };
</source>
and what is more difficult to see is we are also concerned with <idl>com.sun.star.ui.dialogs.ExecutableDialogresults</idl> [[SDKCppLanguage#To_go_further_:_the_Constant_Type_Problem|IDL constants]]:
<source lang="idl">
//Listing 8 ExecutableDialogresults values : IDL File
// IDL
module com { module sun { module star { module ui { module dialogs {
constants ExecutableDialogResults
{
const short CANCEL = 0;
const short OK = 1;
};
}; }; }; }; };
</source>
The way to obtain the FilePicker dialog can be explained as follow. First you have to obtain a <idl>com.sun.star.ui.dialogs.XFilePicker</idl> interface. After we use a setDisplayDirectory for an example, then execute the dialog box and finally get the first of chosen files.
<source lang="cpp">
//Listing 9 a File Picker Dialog
// LINUX C++ (Only the file path is LINUX-like)
// based on Bernard Marcelly's Example (Book p512)
// Don't forget #include <osl/file.hxx>
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/"),sDocUrl);

// Don't forget to add : using namespace com::sun::star::ui::dialogs;
// Don't forget to add : #include <com/sun/star/ui/dialogs/XFilePicker.hpp>
// Don't forget to add "com.sun.star.ui.dialogs.XFilePicker \" in the makefile
// Query the XFilePicker interface

Reference< XFilePicker > rFilePicker = Reference< XFilePicker >
( rOfficeServiceManager->createInstance(
OUString( RTL_CONSTASCII_USTRINGPARAM(
"com.sun.star.ui.dialogs.FilePicker" ))), UNO_QUERY );

rFilePicker->setDisplayDirectory( sDocUrl);
short result=rFilePicker->execute();

// Don't forget to add : #include <com/sun/star/ui/dialogs/ExecutableDialogResults.hpp>
// Don't forget to add "com.sun.star.ui.dialogs.ExecutableDialogResults \" in the makefile
if (result == ExecutableDialogResults::OK)
ShowMessageBox( rToolkit, rFrame,OUString::createFromAscii("Result") ,
rFilePicker->getFiles()[0] );
</source>
It is possible to modify the filter names with the <idl>com.sun.star.ui.dialogs.XFilterManager</idl> interface. Here is the corresponding IDL file :
<source lang="idl">
//Listing 10 XFilterManager Interface : IDL File
// IDL
module com { module sun { module star { module ui { module dialogs {
interface XFilterManager: com::sun::star::uno::XInterface
{
void appendFilter( [in] string aTitle, [in] string aFilter )
raises( ::com::sun::star::lang::IllegalArgumentException );
void setCurrentFilter( [in] string aTitle )
raises( ::com::sun::star::lang::IllegalArgumentException );
string getCurrentFilter( );
};
}; }; }; }; };
</source>
and now a C++ example which use this interface :
<source lang="cpp">
//Listing 11 Using the File Picker
// LINUX C++
// Don't forget #include <osl/file.hxx>
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/"),sDocUrl);
// Don't forget to add : using namespace com::sun::star::ui::dialogs;
// Don't forget to add : #include <com/sun/star/ui/dialogs/XFilePicker.hpp>
// Don't forget to add "com.sun.star.ui.dialogs.XFilePicker \" in the makefile
// Reference< XFilePicker > rFilePicker(rDesktop,UNO_QUERY);
Reference< XFilePicker > rFilePicker = Reference< XFilePicker >
( rOfficeServiceManager->createInstance(
OUString( RTL_CONSTASCII_USTRINGPARAM(
"com.sun.star.ui.dialogs.FilePicker" ))), UNO_QUERY );

rFilePicker->setDisplayDirectory( sDocUrl);

// Don't forget to add : #include <com/sun/star/ui/dialogs/XFilterManager.hpp>
// Don't forget to add "com.sun.star.ui.dialogs.XFilterManager \" in the makefile
Reference< XFilterManager > rFilterManager (rFilePicker, UNO_QUERY);
rFilterManager->appendFilter(OUString::createFromAscii("Texts"),
OUString::createFromAscii("*.txt"));
rFilterManager->appendFilter(OUString::createFromAscii("Docs OpenOffice"),
OUString::createFromAscii("*.sxw;*.sxc"));
rFilterManager->setCurrentFilter(OUString::createFromAscii("Docs OpenOffice"));
short result=rFilePicker->execute();

// Don't forget to add : #include <com/sun/star/ui/dialogs/ExecutableDialogResults.hpp>
// Don't forget to add "com.sun.star.ui.dialogs.ExecutableDialogResults \" in the makefile
if (result == ExecutableDialogResults::OK)
ShowMessageBox( rToolkit, rFrame,OUString::createFromAscii("Result") ,
rFilePicker->getFiles()[0] );
</source>
See also <idl>com.sun.star.ui.dialogs.XFilePicker</idl> and <idl>com.sun.star.ui.dialogs.XFilterManager</idl> interfaces and <idl>com.sun.star.ui.dialogs.ExecutableDialogResults</idl> constants.

It's time to show how to construct a save as Dialog.

==Save as Dialog==
We again start from a Bernard Marcelly's example. Our problem is to translate these OOoBasic lines :
<source lang="oobas">
'Listing 12 Save Dialog
REM ***** BASIC *****
FP=CreateUnoService("com.sun.star.ui.dialogs.FilePicker")
Dim FPtype(0) As Integer
FPtype(0)=com.sun.star.ui.dialogs.TemplateDescription.FILESAVE_SIMPLE
With FP
.initialize(FPtype())
....
End With
</source>
particularly the « initialize » method.
At first, we look for the constant to transform the previous FilePicker dialog. The constants are defined in the <idl>com.sun.star.ui.dialogs.TemplateDescription</idl> file as descibed below ([[SDKCppLanguage#To_go_further_:_the_Constant_Type_Problem|see how to use UNO constants with C++]]) :
<source lang="idl">
//Listing 13 TemplateDescription Constants : IDL File
// IDL
module com { module sun { module star { module ui { module dialogs {
constants TemplateDescription
{
const short FILEOPEN_SIMPLE = 0;
const short FILESAVE_SIMPLE = 1;
const short FILESAVE_AUTOEXTENSION_PASSWORD = 2;
const short FILESAVE_AUTOEXTENSION_PASSWORD_FILTEROPTIONS = 3;
const short FILESAVE_AUTOEXTENSION_SELECTION = 4;
const short FILESAVE_AUTOEXTENSION_TEMPLATE = 5;
const short FILEOPEN_LINK_PREVIEW_IMAGE_TEMPLATE = 6;
const short FILEOPEN_PLAY = 7;
const short FILEOPEN_READONLY_VERSION = 8;
const short FILEOPEN_LINK_PREVIEW = 9;
const short FILESAVE_AUTOEXTENSION = 10;
};
}; }; }; }; };
</source>
Looking for initialize method, we have a look in <idl>com.sun.star.ui.dialogs.FilePicker</idl> service :
<source lang="idl">
//Listing 14 FilePiker service : IDL File
// IDL
module com { module sun { module star { module ui { module dialogs {
interface XFilePicker;
interface XFilePickerNotifier;
interface XFilePickerControlAccess;
interface XFilterManager;
interface XFilePreview;
interface XFilterGroupManager;

service FilePicker
{
[optional, property] string HelpURL;
interface XFilePicker;
interface XFilePickerNotifier;
interface XFilterManager;
[optional] interface XFilePreview;
[optional] interface XFilePickerControlAccess;
[optional] interface XFilterGroupManager;
[optional] interface com::sun::star::lang::XInitialization;
[optional] interface com::sun::star::util::XCancellable;
interface com::sun::star::lang::XComponent;
interface com::sun::star::lang::XServiceInfo;
interface com::sun::star::lang::XTypeProvider;
};
}; }; }; }; };
</source>
where you see an <idl>com.sun.star.lang.XInitialization</idl> interface. Therefore we give the XInitialization.idl file :
<source lang="idl">
//Listing 15 XInitialisation Interface : IDL File
// IDL
module com { module sun { module star { module lang {
interface XInitialization: com::sun::star::uno::XInterface
{
void initialize( [in] sequence<any> aArguments )
raises( com::sun::star::uno::Exception );

};
}; }; }; };
</source>
It's OK, we get it. We see we have to pass an any sequence to the initialize procedure. It's time to write the C++ corresponding code.
<source lang="cpp">
//Listing 16 Invoking the Save Dialog
// LINUX C++
// inspired by Bernard Marcelly's Example p515
// Don't forget #include <osl/file.hxx>
OUString sDocUrl;
osl::FileBase::getFileURLFromSystemPath(
OUString::createFromAscii("/home/smoutou/"),sDocUrl);
// Don't forget to add : using namespace com::sun::star::ui::dialogs;
// Don't forget to add : #include <com/sun/star/ui/dialogs/XFilePicker.hpp>
// Don't forget to add "com.sun.star.ui.dialogs.XFilePicker \" in the makefile
// Reference< XFilePicker > rFilePicker(rDesktop,UNO_QUERY);
Reference< XFilePicker > rFilePicker = Reference< XFilePicker >
( rOfficeServiceManager->createInstance(
OUString( RTL_CONSTASCII_USTRINGPARAM(
"com.sun.star.ui.dialogs.FilePicker" ))), UNO_QUERY );

rFilePicker->setDisplayDirectory( sDocUrl);

// Don't forget to add : #include <com/sun/star/ui/dialogs/XFilterManager.hpp>
// Don't forget to add "com.sun.star.ui.dialogs.XFilterManager \" in the makefile
Reference< XFilterManager > rFilterManager (rFilePicker, UNO_QUERY);

// Don't forget to add : #include <com/sun/star/lang/XInitialization.hpp>
// Don't forget to add "com.sun.star.lang.XInitialization \" in the makefile
Reference< XInitialization > rInitialize (rFilePicker, UNO_QUERY);
Sequence < Any > info(1);

// Don't forget to add : #include <com/sun/star/ui/dialogs/TemplateDescription.hpp>
// Don't forget to add "com.sun.star.ui.dialogs.TemplateDescription \" in the makefile
info[0] <<= (short) TemplateDescription::FILESAVE_SIMPLE;
rInitialize-> initialize(info);

rFilterManager->appendFilter(OUString::createFromAscii("Texts"),
OUString::createFromAscii("*.txt"));
rFilterManager->appendFilter(OUString::createFromAscii("Docs OpenOffice"),
OUString::createFromAscii("*.sxw;*.sxc"));
rFilterManager->setCurrentFilter(OUString::createFromAscii("Docs OpenOffice"));
short result=rFilePicker->execute();

// Don't forget to add : #include <com/sun/star/ui/dialogs/ExecutableDialogResults.hpp>
// Don't forget to add "com.sun.star.ui.dialogs.ExecutableDialogResults \" in the makefile
if (result == ExecutableDialogResults::OK)
ShowMessageBox( rToolkit, rFrame,OUString::createFromAscii("Result") ,
rFilePicker->getFiles()[0] );
</source>
This code uses <idl>com.sun.star.ui.dialogs.XFilePicker</idl>, <idl>com.sun.star.ui.dialogs.XFilterManager</idl>, <idl>com.sun.star.lang.XInitialization</idl> interfaces and <idl>com.sun.star.ui.dialogs.ExecutableDialogResults</idl> UNO constants.

We are interesting now with generalising our previous work with Dialog Box.

== Run Time Dialog Box ==
Read also [[Documentation/DevGuide/Basic/Creating_Dialogs_at_Runtime|Developer's Guide]] and [[Documentation/BASIC_Guide/Dialogs|OOoBasic and Dialogs]].

After the previous examples inspired by Bernard Marcelly's book, it's time to start with an example inspired from Andrew Pitonyak's book. OOoBasic is particulary difficult to translate in these situations. We then choose to start from a Java example in :
<OpenOffice.org1.1_SDK>/examples/DevelopersGuide/BasicAndDialogs/CreatingDialogs
with the file SampleDialog.java
For this example we use [[CppSDKAuthors|GAP's]] helper provided [[Constructing_Helpers#The_GAP.27s_Helper|here]].
{{Documentation/Note|Dialogs tackled in this section are runtime dialogs. Since recent evolution of OpenOffice, it is possible to run OOoBasic Dialog (I mean conceived with Basic IDE) with all programming language. But the [[Documentation/DevGuide/WritingUNO/Using_Dialogs_in_Components|only SDK's examples available]] are for components and in Java, and at the moment, I have no time to explore if it is possible with C++ automation examples and in C++.}}

We give now the complete code. Because it's a lot of code you have to look at <idl>com.sun.star.awt.XActionListener</idl>, <idl>com.sun.star.awt.XControlContainer</idl>, <idl>com.sun.star.lang.XMultiServiceFactory</idl>, <idl>com.sun.star.uno.XInterface</idl>, <idl>com.sun.star.frame.XComponentLoader</idl>, <idl>com.sun.star.uno.XComponentContext</idl>, <idl>com.sun.star.lang.XMultiComponentFactory</idl>, <idl>com.sun.star.beans.XPropertySet</idl>, <idl>com.sun.star.container.XNameContainer</idl>, <idl>com.sun.star.awt.XButton</idl>, <idl>com.sun.star.awt.XToolkit</idl>, <idl>com.sun.star.awt.XWindow</idl>, <idl>com.sun.star.ui.dialogs.XDialog</idl> interfaces, and <idl>com.sun.star.awt.ActionEvent</idl> event, and also <idl>com.sun.star.frame.Desktop</idl>, <idl>com.sun.star.awt.UnoControlDialogModel</idl>, <idl>com.sun.star.awt.UnoControlButtonModel</idl> services) :
<source lang="cpp">
//Listing 17 Our first Run Time Dialog Box
// C++ (GAP example)
#include "SimpleOOConnection.cpp"
...
// First an event listener for the Button
// Don't forget the #include <cppuhelper/implbase1.hxx>
typedef ::cppu::WeakImplHelper1< ::com::sun::star::awt::XActionListener > ActionListenerHelper;
/** action listener
*/
class ActionListenerImpl : public ActionListenerHelper
{
private :
int _nCounts;
Reference< XControlContainer > _xControlCont;
//XControlContainer _xControlCont;

public :
ActionListenerImpl(const Reference< XControlContainer >& xControlCont) {
_xControlCont = xControlCont;
_nCounts = 0;
}

// XEventListener
virtual void SAL_CALL disposing (const com::sun::star::lang::EventObject& aEventObj )
throw(::com::sun::star::uno::RuntimeException) {
// _xControlCont = NULL;
cout << "object listened to will be disposed"<<endl;
}

// XActionListener
virtual void SAL_CALL actionPerformed (const ::com::sun::star::awt::ActionEvent& rEvent )
throw ( RuntimeException) {
// increase click counter
_nCounts++;
cout << "OK : " << _nCounts << endl;
}
};

int main()
{
SimpleOOConnection sOOConnection1;

//instantiating connection to Remote Service Manager
Reference< XMultiServiceFactory > xRemoteServiceManager=sOOConnection1.connect_ooffice
("uno:socket,host=localhost,port=8100;urp;StarOffice.ServiceManager");
//checks whether getting Remote Service Manager or Not
if(!xRemoteServiceManager.is())
{
cout<<"Error in connection"<<endl;
return 1;
}

// setting Desktop reference to desktop
Reference< XInterface > desktop =xRemoteServiceManager->createInstance
(OUString::createFromAscii("com.sun.star.frame.Desktop" ));

// Query for the XUnoUrlResolver interface for loading Desktop
Reference< XComponentLoader > xComponentLoader( desktop, UNO_QUERY );

//////////////////////////////////////////////////////////////////////////////////////
Any any;
sal_Int32 value;

Reference< XComponentContext > xComponentContext =
defaultBootstrap_InitialComponentContext();

// retrieve the servicemanager from the context
Reference< XMultiComponentFactory > xMultiComponentFactory =
xComponentContext->getServiceManager();
/************************************************************************************
Reference<XInterface> dialogModel = xMultiComponentFactory->createInstanceWithContext(
OUString::createFromAscii("com.sun.star.awt.UnoControlDialogModel"),
xComponentContext );
************************************************************************************/
/////////////////////////////////////////////////////////////////////////////////////////

Reference<XInterface> dialogModel = xRemoteServiceManager->createInstance
(OUString::createFromAscii("com.sun.star.awt.UnoControlDialogModel"));
cout<<"hi"<<endl;

///////////////////////////////////////////////////////////////////////////////////////////

Reference< XPropertySet >xPSetDialog(dialogModel,UNO_QUERY );

value=150;
any<<=value;
xPSetDialog->setPropertyValue( OUString::createFromAscii("PositionX"), any );
xPSetDialog->setPropertyValue( OUString::createFromAscii("PositionY"), any );
xPSetDialog->setPropertyValue( OUString::createFromAscii("Width"), any );
xPSetDialog->setPropertyValue( OUString::createFromAscii("Height"), any );
any<<=OUString::createFromAscii( "Runtime Dialog Demo" );
xPSetDialog->setPropertyValue( OUString::createFromAscii("Title"), any );

Reference<XMultiServiceFactory> xMultiServiceFactory(dialogModel,UNO_QUERY );

Reference< XInterface > buttonModel = xMultiServiceFactory->createInstance
(OUString::createFromAscii("com.sun.star.awt.UnoControlButtonModel") );

Reference< XPropertySet >xPSetButton(buttonModel,UNO_QUERY );

value=20;
any<<=value;
xPSetButton->setPropertyValue( OUString::createFromAscii("PositionX"), any );

value=70;
any<<=value;
xPSetButton->setPropertyValue( OUString::createFromAscii("PositionY"), any );
value=50;
any<<=value;
xPSetButton->setPropertyValue( OUString::createFromAscii("Width"), any );
value=14;
any<<=value;
xPSetButton->setPropertyValue( OUString::createFromAscii("Height"), any );
any<<=OUString::createFromAscii("Button1");
xPSetButton->setPropertyValue( OUString::createFromAscii("Name"), any );
value=1;
any<<=value;

//xPSetButton->setPropertyValue( OUString::createFromAscii("TabIndex"), any );
any<<=OUString::createFromAscii( "Click Me" );

xPSetButton->setPropertyValue( OUString::createFromAscii("Label"), any );

// insert the control models into the dialog model
Reference< XNameContainer >xNameCont(dialogModel,UNO_QUERY );
any<<=buttonModel;

xNameCont->insertByName( OUString::createFromAscii("Button1"), any );

// create the dialog control and set the model
Reference<XInterface> dialog = xRemoteServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.awt.UnoControlDialog"));

Reference<XControl> xControl(dialog,UNO_QUERY );
Reference<XControlModel >xControlModel(dialogModel,UNO_QUERY );
xControl->setModel( xControlModel );

// add an action listener to the button control
Reference< XControlContainer >xControlCont(dialog ,UNO_QUERY );
Reference< XInterface > objectButton = xControlCont->getControl(
OUString::createFromAscii("Button1") );
Reference< XButton >xButton(objectButton ,UNO_QUERY);

ActionListenerImpl *xListener = new ActionListenerImpl( xControlCont );
Reference< XActionListener > xActionListener =
static_cast< XActionListener* > ( xListener );

xButton->addActionListener( xActionListener );

// create a peer
Reference<XInterface> toolkit = xRemoteServiceManager->createInstance(
OUString::createFromAscii("com.sun.star.awt.ExtToolkit"));
Reference< XToolkit >xToolkit(toolkit , UNO_QUERY );

Reference< XWindow >xWindow(xControl , UNO_QUERY );
xWindow->setVisible( true );
xControl->createPeer( xToolkit,'\0' );//create instance of XWindowPeer

// execute the dialog
Reference< XDialog >xDialog(dialog , UNO_QUERY );
xDialog->execute();

// dispose the dialog
Reference< XComponent > xComponent(dialog,UNO_QUERY );
xComponent->dispose();

/////////////////////////////////////////////////////////////////////////////////////

return 0;
}
</source>
This code will print out :
<pre>
hi
OK : 1
OK : 2
OK : 3
OK : 4
OK : 5
OK : 6
OK : 7
OK : 8
object listened to will be disposed
</pre>
When clicking on the button it increment and prints out the new value.
From this code any tips to manage a dialog box can be hired :
# create a dialog model service, dialogModel variable in the above code
# query a XPropertySet interface to set any properties (x y positions, size, title, ..)
# create all controls with the same previous both rules : query a control model first, and then query a XPropertySet interface to set any properties
# query a XNameContainer from the dialog model
# insert every control model into the dialog model with this container
# create the dialog control and query first aXControl interface and second a XControlModedl interface to set the model
# add action listener if needed
# after creating a peer run the dialog

== Complete Translation of a Java example ==

{{:First Dialog}}

== Text Control example ==
We want now to construct a more complex [[dialog_box_with_an_edit_control|dialog box with a text control]].

== List Box example ==
We want now to construct a [[dialog_box_with_an_List_Box|dialog box with a list box]].

== Radio button example ==

We want now to construct a [[dialog_box_with_an_Radio_Button|dialog box with a radio button]].

== TO DO ==

[http://api.openoffice.org/docs/DevelopersGuide/Components/Components.xhtml Developer's Guide] states it is possible to construct a component with a dialog that have been created with the Dialog Editor integrated in the OpenOffice.org Basic IDE. I think the same is possible with a binary executable and I have to work around this subject.

{{Template:Home_Page}}

=See also=
* [[Documentation/DevGuide/Basic/Creating_Dialogs_at_Runtime|Creating Dialogs at Runtime]] in Developer's Guide
* [[Framework/Article/Easy_To_Use_Message_Boxes|Easy To Use Message Boxes]] in OOoBasic
* [[Documentation/BASIC_Guide/Dialogs|OOoBasic and Dialogs]]
* [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno|C++ and UNO tutorial]]
*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* [[Framework/Tutorial/Popup_Menu_Controller|Popup Menu Controller]] and C++
* [[Framework/Tutorial/Statusbar_Controller|Statusbar Controler]] and C++
* [[Treecontrol|The New Tree Contol]]
* [[Framework/Article/Generic_UNO_Interfaces_for_complex_toolbar_controls|Generic UNO Interfaces for complex toolbar controls]]
* 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:Development]]
[[Category:Cpp]]
[[Category:Uno]]
[[Category:Tutorial]]

PrinttoWriter.py

2009-12-03T06:02:27Z

Newacct:

==Danny.OOo.PrintToWriter.py ==

This makes it easy and convenient to '''print''' a bunch of text into a Writer document.

See the example routine in the module that shows how easy this module is to use, and how useful it can be.

<source lang=python>
#**********************************************************************
# If you make changes, please append to the change log below.
#
# Change Log
# Danny Brewer Revised 2004-06-05-01
#
#**********************************************************************

# OOo's libraries
import uno

# Danny's libraries
from Danny.OOo.OOoLib import StarDesktop

com_sun_star_text_ControlCharacter_PARAGRAPH_BREAK = uno.getConstantByName( "com.sun.star.text.ControlCharacter.PARAGRAPH_BREAK" )
com_sun_star_text_ControlCharacter_LINE_BREAK = uno.getConstantByName( "com.sun.star.text.ControlCharacter.LINE_BREAK" )
com_sun_star_text_ControlCharacter_HARD_HYPHEN = uno.getConstantByName( "com.sun.star.text.ControlCharacter.HARD_HYPHEN" )
com_sun_star_text_ControlCharacter_SOFT_HYPHEN = uno.getConstantByName( "com.sun.star.text.ControlCharacter.SOFT_HYPHEN" )
com_sun_star_text_ControlCharacter_HARD_SPACE = uno.getConstantByName( "com.sun.star.text.ControlCharacter.HARD_SPACE" )
com_sun_star_text_ControlCharacter_APPEND_PARAGRAPH = uno.getConstantByName( "com.sun.star.text.ControlCharacter.APPEND_PARAGRAPH" )

class PrintToWriter:
"""A class which allows conveniently printing stuff into a Writer document.
Very useful for debugging, general output purposes, or even for creating reports."""
def __init__( self ):
self.oWriterDoc = StarDesktop.loadComponentFromURL( "private:factory/swriter", "_blank", 0, () )
self.oWriterText = self.oWriterDoc.getText()
self.oWriterCursor = self.oWriterText.createTextCursor()

def writeLn( self, *args ):
if len( args ) > 0:
self.write( *args )
self.writeParagraphBreak()

def write( self, arg1, *argsRest ):
self.writeOne( arg1 )
for arg in argsRest:
self.writeTab()
self.writeOne( arg )

def writeOne( self, arg, bAbsorb=False ):
self.writeString( str( arg ), bAbsorb )

def writeTab( self, bAbsorb=False ):
self.writeString( "\t", bAbsorb )

def writeParagraphBreak( self, bAbsorb=False ):
self.writeControlCharacter( com_sun_star_text_ControlCharacter_PARAGRAPH_BREAK, bAbsorb )

def writeString( self, cString, bAbsorb=False ):
self.oWriterText.insertString( self.oWriterCursor, cString, bAbsorb )

def writeControlCharacter( self, nCtrlChar, bAbsorb=False ):
self.oWriterText.insertControlCharacter( self.oWriterCursor, nCtrlChar, bAbsorb )

def example_PrintToWriter():
"""An example of how to use the PrintToWriter class to trivially create
a new Writer document, and write out text into it."""
oOutput = PrintToWriter()
oOutput.writeLn( "Hello World" )
oOutput.write( "String", 123, 456.23, True )
oOutput.writeLn()
oOutput.writeLn()

oOutput.writeLn( "Tab delimited values..." )

oOutput.write( 123 )
oOutput.writeTab()
oOutput.write( 456 )
oOutput.writeTab()
oOutput.write( 789 )
oOutput.writeLn()

oOutput.write( 465 )
oOutput.writeTab()
oOutput.write( 522 )
oOutput.writeTab()
oOutput.write( 835 )
oOutput.writeLn()

oOutput.write( 886 )
oOutput.writeTab()
oOutput.write( 164 )
oOutput.writeTab()
oOutput.write( 741 )
oOutput.writeLn()
</source>
== How it Works ==
PrintToWriter.py code is really just a way to:
* create the enviroment
* create a document
* generate the content
* insert it within a document

So first we need to create the '''enviroment''' so that we don't generate a verbose code, we need to insert it into variable.

To create the enviroment we need a couple of things, first we import a library, which already save us a bunch of code in order to reference to UNO. The next step is to choose the fomat element we will need to input. For tha we use the uno.getConstantByName and point to the [http://api.openoffice.org/docs/common/ref/com/sun/star/text/ControlCharacter.html ControlCharacter] component which includes all the format we need.

* Paragraph Break - Insert a paragraph break
* Line Break - Inserts a line break inside of the paragraph
* Hard Hyphen - A character that appears like a dash, but prevents hyphenation at its position
* Soft Hyphen - Marks a preferred position for hyphenation
* Hard Space - A character that appears like a space, but prevents hyphenation at this point
* Append Paragraph - A new paragraph is appended

The next step is to generate the class for '''PrintToWriter''', this is the class that this file is about. Then we need to load the writer component, on like 59. We use the '''getText()''' function so we can access the text area from the writer's component. Once we are there, we explicity activate the Cursor.

We go on using the following functions:

* writeLn = Insert a break on end of Line
* write =
* writeOne = Write String
* writeTab = Insert a '''\t''' value as a string
* writeParagraphBreak = we call on the PARAGRAPH_BREAK component
* writeString = We use cString after the Cursor
* writeControlCharacter = nCtrlChar

The example_PrinterToWrite is basically we execute the functtons we create under the '''PrintToWriter class'''. This will be enough for you to see how we can use the functions to insert content and how it works the different funmction.

[[Category:Python]]

UNO component packaging ja

2009-12-03T06:01:23Z

Newacct:

= Python UNO コンポーネント =
このページでは作成済みの UNO コンポーネントのパッケージ化および配布方法を説明します。非常に簡単な例として私が作成した ''Wavelet'' クラスを使用します。

より詳細が必要なら [[http://api.openoffice.org/docs/DevelopersGuide/Components/Components.htm Developers Guide]] を参照してください。

=Python ローダー=
Python ローダーは自身があるパスにないクラスを読み込むことができません。そのため、使用する全てのクラスおよびモジュールを OpenOffice.org Python ライブラリのディレクトリにコピーしなければいけません。さらに、実行前に OOo を再起動する必要があるかもしれません。
訳注: OOo 2.4 以降ではユーザー独自の Python モジュールをインポートする方法が実装されています。

=Python コンポーネント例=

==Wavelet クラス==
私が作成した ''Wavelet'' クラスを使用します。このクラスはチェコ語の前置詞の前のスペースを改行されないスペースで置換します。次のコードを ''Wavelet.py'' ファイルに保存してください。

<source lang=python>

import uno
import unohelper
from com.sun.star.task import XJobExecutor

class Wavelet( unohelper.Base, XJobExecutor ):
def __init__( self, ctx ):
self.ctx = ctx

def trigger( self, args ):
desktop = self.ctx.ServiceManager.createInstanceWithContext(
"com.sun.star.frame.Desktop", self.ctx )

doc = desktop.getCurrentComponent()

try:
search = doc.createSearchDescriptor()
search.SearchRegularExpression = True
search.SearchString = "\\<(k|s|v|z|o|u|i|a) "

found = doc.findFirst( search )
while found:
found.String = found.String.replace( " ", u"\xa0" )
found = doc.findNext( found.End, search)

except:
pass
</source>

== Wavelet クラスの登録 ==
OpenOffice.org にコンポーネントのメインクラスを伝えなければいけません。次のコードを ''Wavelet.py'' ファイルの最後に追加してください。

<source lang=python>
g_ImplementationHelper = unohelper.ImplementationHelper()
g_ImplementationHelper.addImplementation(
Wavelet,
"name.vojta.openoffice.Wavelet",
("com.sun.star.task.Job",),)
</source>

= コンポーネントの統合 =

==アイコン==
あなた独自のメニューの項目やツールバーのボタンのアイコンを作成できます。最も簡単なのは TrueColor の BMP ファイルを二つ作成することです。一つ目は 26 x 26 pixel に、もう一つは 16x16 pixel サイズにしておきます。

アルファ (透過) を利用したいのであれば ''#FF00FF'' (RGB) (マゼンタ) を使いましょう。

このアイコンは任意で作成します。無理に作成する必要はありません。

==Addons.xcu==
コンポーネント統合のためのコンフィグレーションを ''Addons.xcu'' ファイルに記述します。

===ヘッダ===
このファイルのヘッダは次のようにしなければいけません。

<source lang=xml>
<?xml version="1.0" encoding="UTF-8"?>
<oor:component-data xmlns:oor="http://openoffice.org/2001/registry"
xmlns:xs="http://www.w3.org/2001/XMLSchema" oor:name="Addons"
oor:package="org.openoffice.Office">

<node oor:name="AddonUI">
</source>

===オフィースメニューバー===
次のパートでは ''Czech'' (または ''Cestina''、ユーザーインターフェースの言語設定により違います) という新規メニュー項目をおよび "Wavelet" メニュー項目を作成します。

このメニュー項目は ''name.vojta.openoffice.Wavelet?execute'' ''URL'' に関連付けます。これはメニューをクリックしたときに ''Wavelet.trigger'' メソッドが ''execute'' という引数と共に呼ばれるということです。

このメニューは OpenOffice.org Writer にのみ表示されます。

<source lang=xml>
<node oor:name="OfficeMenuBar">
<node oor:name="name.vojta.openoffice.Wavelet" oor:op="replace">
<prop oor:name="Title" oor:type="xs:string">
<value/>
<value xml:lang="en-US">Czech</value>
<value xml:lang="cs">Cestina</value>
</prop>
<prop oor:name="Target" oor:type="xs:string">
<value>_self</value>
</prop>
<prop oor:name="ImageIdentifier" oor:type="xs:string">
<value/>
</prop>
<node oor:name="Submenu">
<node oor:name="m1" oor:op="replace">
<prop oor:name="URL" oor:type="xs:string">
<value>service:name.vojta.openoffice.Wavelet?execute</value>
</prop>
<prop oor:name="Title" oor:type="xs:string">
<value/>
<value xml:lang="en-US">Wavelet</value>
<value xml:lang="cs">Vlnka</value>
</prop>
<prop oor:name="Target" oor:type="xs:string">
<value>_self</value>
</prop>
<prop oor:name="Context" oor:type="xs:string">
<value>com.sun.star.text.TextDocument</value>
</prop>
</node>
</node>
</node>
</node>
</source>

===オフィースツールバー===
次のパートでは一つのボタンを持った新規ツールバー (''Add-on 1'' や ''Add-on 2'', ... というツールバー名を持ったもの) を作成します。このボタンは ''name.vojta.openoffice.Wavelet?execute'' ''URL'' に関連付けます。これは、ツールバーのこのボタンが押されたときに "Wabelet.trigger" メソッドが実行されるということです。''execute'' が引数として渡されます。

'''注''': ツールバー名を変更することができません。これは旧バージョン 1.1.x 系との互換性のためです。

<source lang=xml>
<node oor:name="OfficeToolBar">
<node oor:name="name.vojta.openoffice.Wavelet" oor:op="replace">
<node oor:name="m1" oor:op="replace">
<prop oor:name="URL" oor:type="xs:string">
<value>service:name.vojta.openoffice.Wavelet?execute</value>
</prop>
<prop oor:name="ImageIdentifier" oor:type="xs:string">
<value/>
</prop>
<prop oor:name="Title" oor:type="xs:string">
<value/>
<value xml:lang="en-US">Wavelet</value>
<value xml:lang="cs">Vlnka</value>
</prop>
<prop oor:name="Target" oor:type="xs:string">
<value>_self</value>
</prop>
<prop oor:name="Context" oor:type="xs:string">
<value>com.sun.star.text.TextDocument</value>
</prop>
</node>
</node>
</node>
</source>

===アイコン===
アイコンをすべての ''URL'' と関連付けることができます。アイコンを ''name.vojta.openoffice.Wavelet?execute'' ''URL'' と関連付けることにします。これは、同じ "URL" に関連付けられたすべてのコントロール (メニュー項目、ボタンなど) がこれらのアイコンを使用するということです。

'''注:''' %origin% は UNO コンポーネントパッケージです。これについては後述します。

<source lang=xml>
<node oor:name="Images">
<node oor:name="name.vojta.openoffice.Wavelet.image1" oor:op="replace">
<prop oor:name="URL">
<value>service:name.vojta.openoffice.Wavelet?execute</value>
</prop>
<node oor:name="UserDefinedImages">
<prop oor:name="ImageSmallURL" oor:type="xs:string">
<value>%origin%/images/WaveletSmall.bmp</value>
</prop>
<prop oor:name="ImageBigURL" oor:type="xs:string">
<value>%origin%/images/WaveletBig.bmp</value>
</prop>
</node>
</node>
</node>
</source>

===フッタ===
開いているセクションをすべて閉じます。

<source lang=xml>
</node>
</oor:component-data>
</source>

=UNO コンポーネントパッケージ=
UNO コンポーネントパッケージは単純な ZIP ファイルです。パッケージは ''Addons.xcu'' ファイル、アイコンを入れた ''images'' ディレクトリおよび Python コンポーネントの実装を含んでいることは言うまでもありません。

==パッケージ作成==
次のコマンドでサンプルパッケージを作成できます。

<source lang=bash>
zip -r Wavelet.uno.zip Addons.xcu Wavelet.py images
</source>
最終的に ''Wavelet.uno.zip'' パッケージに次のファイルが含まれているはずです。

<source lang=bash>
Wavelet.uno.zip
Addons.xcu
Wavelet.py
images/WaveletBig.bmp
images/WaveletSmall.bmp
</source>
'''注:''' ''%origin%'' は ''Wavelet.uno.zip'' になります。従って、 ''%origin%/images/WaveletBig.bmp'' は ''Wavelet.uno.zip'' ファイル中の ''WaveletBig.bmp'' ファイルを指します。
訳注: 現在の実装では %origin% はコンフィグレーションファイルの位置を指します。

==インストール==
UNO コンポーネントを拡張機能マネージャ (ツールメニューにあると思われます) または ''unopkg'' ツールでインストールできます。

<source lang=bash>
/opt/openoffice.org1.9.103/program/unopkg add Wavelet.uno.zip
</source>

==アンインストール==
UNO コンポーネントを拡張機能マネージャ (ツールメニューにあるでしょう) または ''unopkg'' ツールでアンインストールできます。

<source lang=bash>
/opt/openoffice.org1.9.103/program/unopkg remove Wavelet.uno.zip
</source>

=Python コンポーネントのテスト=
Python UNO コンポーネントをテストするためにそのコンポーネントをインストールする必要はありません。実行されている OpenOffice.org のインスタンスに接続して UNO コンポーネントをテストできます。

==コード==
次のコードを ''Wavelet.py'' ファイルの最後に追加してください。

<source lang=python>
if __name__ == "__main__":
import os

# Start OpenOffice.org, listen for connections and open testing document
os.system( "/etc/openoffice.org-1.9/program/soffice '-accept=socket,host=localhost,port=2002;urp;' -writer ./WaveletTest.odt &" )

# Get local context info
localContext = uno.getComponentContext()
resolver = localContext.ServiceManager.createInstanceWithContext(
"com.sun.star.bridge.UnoUrlResolver", localContext )

ctx = None

# Wait until the OO.o starts and connection is established
while ctx == None:
try:
ctx = resolver.resolve(
"uno:socket,host=localhost,port=2002;urp;StarOffice.ComponentContext" )
except:
pass

# Trigger our job
wavelet = Wavelet( ctx )
wavelet.trigger( () )
</source>

==テスト==
UNO コンポーネントをテストするには、''Wavelet.py'' ファイルを Python インタープレタからただ実行してください。

<source lang=bash>
/opt/openoffice.org1.9.103/program/python ./Wavelet.py
</source>

==概要==
このパートでは次のことを行います。

OpenOffice.org を開始して ''WaveletTest.odt'' ファイルを開きます。

接続が確立するまでループします。

コンポーネントを実行中の OpenOffice.org context で開始します。

'''注:''' 実際の UNO コンポーネントパッケージを作成するときにこのパートを削除するのを忘れないでください。もしくはコメントにしてください。
訳注: 実際には削除する必要はありません。パッケージ内で実行されるときにはモジュールが __main__ でないので実行されません。

=参照=
* [http://api.openoffice.org/docs/DevelopersGuide/Extensions/Extensions.xhtml Extensions] chapter of the Developers Guide
* Using C++ with OOo SDK : [[Constructing_Components| Constructing Component in C++]]
*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* Daniel Bolzle's [http://udk.openoffice.org/cpp/man/component_tutorial.html tutorial] : Writing a simple UNO component.
* [[UNO_component_packaging|Component with Python]]

[[Category:Uno]]
[[Category:Extensions]]

UNO component packaging

2009-12-03T06:01:03Z

Newacct:

=Python UNO component=
This page shows you how to pack and deploy already written UNO component. I'm using my ''Wavelet'' class as an example of a very simple component.

More detailed info is in the [[http://api.openoffice.org/docs/DevelopersGuide/Components/Components.htm Developers Guide]].

=Python loader=
The Python loader is not able load classes that are not it its own path. Thus it's necessary to copy any classes or modules you will use into the OPenOffice Python lib directory, and it may be necessary to restart OOo before they are picked up.

=Sample Python component=

==Wavelet class==
We will use my sample ''Wavelet'' class which replaces space with non breaking space before the Czech prepositions. Put the following code in the ''Wavelet.py'' file.

<source lang=python>

import uno
import unohelper
from com.sun.star.task import XJobExecutor

class Wavelet( unohelper.Base, XJobExecutor ):
def __init__( self, ctx ):
self.ctx = ctx

def trigger( self, args ):
desktop = self.ctx.ServiceManager.createInstanceWithContext(
"com.sun.star.frame.Desktop", self.ctx )

doc = desktop.getCurrentComponent()

try:
search = doc.createSearchDescriptor()
search.SearchRegularExpression = True
search.SearchString = "\\<(k|s|v|z|o|u|i|a) "

found = doc.findFirst( search )
while found:
found.String = found.String.replace( " ", u"\xa0" )
found = doc.findNext( found.End, search)

except:
pass
</source>

==Wavelet class registration==
You have to tell the OpenOffice.org what is the main class of your component. Put the following code at the end of your ''Wavelet.py'' file.

<source lang=python>
g_ImplementationHelper = unohelper.ImplementationHelper()
g_ImplementationHelper.addImplementation(
Wavelet,
"name.vojta.openoffice.Wavelet",
("com.sun.star.task.Job",),)
</source>

=Component integration=

==Icons==
You can create your own icons for the Menu item or the Toolbar button. The easiest way is to create two true color BMP files - the first one should be 26×26 and the second one should be 16×16.

If you want to use alpha (transparent color), use ''#FF00FF'' (RGB) color.

This possibility is optional and you're not forced to create icons.

==Addons.xcu==
Component integration configuration is in the ''Addons.xcu'' file.

===Header===
The header of this file should contain:

<source lang=xml>
<?xml version="1.0" encoding="UTF-8"?>
<oor:component-data xmlns:oor="http://openoffice.org/2001/registry"
xmlns:xs="http://www.w3.org/2001/XMLSchema" oor:name="Addons"
oor:package="org.openoffice.Office">

<node oor:name="AddonUI">
</source>

===Office Menu Bar===
Following part creates new menu item ''Czech'' (or ''Cestina'', depends on the UI language) and the ''Wavelet'' menu item.

This menu item is associated with the ''name.vojta.openoffice.Wavelet?execute'' ''URL''. It means, that when you click on the menuitem, ''Wavelet.trigger'' method will be executed with the ''execute'' as an argument.

This menu will be visible in the OpenOffice.org Writer only.

<source lang=xml>
<node oor:name="OfficeMenuBar">
<node oor:name="name.vojta.openoffice.Wavelet" oor:op="replace">
<prop oor:name="Title" oor:type="xs:string">
<value/>
<value xml:lang="en-US">Czech</value>
<value xml:lang="cs">Cestina</value>
</prop>
<prop oor:name="Target" oor:type="xs:string">
<value>_self</value>
</prop>
<prop oor:name="ImageIdentifier" oor:type="xs:string">
<value/>
</prop>
<node oor:name="Submenu">
<node oor:name="m1" oor:op="replace">
<prop oor:name="URL" oor:type="xs:string">
<value>service:name.vojta.openoffice.Wavelet?execute</value>
</prop>
<prop oor:name="Title" oor:type="xs:string">
<value/>
<value xml:lang="en-US">Wavelet</value>
<value xml:lang="cs">Vlnka</value>
</prop>
<prop oor:name="Target" oor:type="xs:string">
<value>_self</value>
</prop>
<prop oor:name="Context" oor:type="xs:string">
<value>com.sun.star.text.TextDocument</value>
</prop>
</node>
</node>
</node>
</node>
</source>

===Office Toolbar===
Following part creates new toolbar (with name ''Add-on 1'', ''Add-on 2'', …) and one button. This button is associated with the ''name.vojta.openoffice.Wavelet?execute'' ''URL''. It means that the ''Wavelet.trigger'' method will be executed when you click on the button on the toolbar. ''execute'' will be passed as an argument.

'''Note:''' You can't rename the toolbar. It's due to the backwards compatibility with the 1.1.x version.

<source lang=xml>
<node oor:name="OfficeToolBar">
<node oor:name="name.vojta.openoffice.Wavelet" oor:op="replace">
<node oor:name="m1" oor:op="replace">
<prop oor:name="URL" oor:type="xs:string">
<value>service:name.vojta.openoffice.Wavelet?execute</value>
</prop>
<prop oor:name="ImageIdentifier" oor:type="xs:string">
<value/>
</prop>
<prop oor:name="Title" oor:type="xs:string">
<value/>
<value xml:lang="en-US">Wavelet</value>
<value xml:lang="cs">Vlnka</value>
</prop>
<prop oor:name="Target" oor:type="xs:string">
<value>_self</value>
</prop>
<prop oor:name="Context" oor:type="xs:string">
<value>com.sun.star.text.TextDocument</value>
</prop>
</node>
</node>
</node>
</source>

===Icons===
You can associate your icons with any ''URL''. We will associate our icons with ''name.vojta.openoffice.Wavelet?execute'' ''URL''. It means that all controls (menu item, button, …) associated with the same ''URL'' will use these icons.

'''Note:''' %origin% is the UNO component package. We will explain it later.

<source lang=xml>
<node oor:name="Images">
<node oor:name="name.vojta.openoffice.Wavelet.image1" oor:op="replace">
<prop oor:name="URL">
<value>service:name.vojta.openoffice.Wavelet?execute</value>
</prop>
<node oor:name="UserDefinedImages">
<prop oor:name="ImageSmallURL" oor:type="xs:string">
<value>%origin%/images/WaveletSmall.bmp</value>
</prop>
<prop oor:name="ImageBigURL" oor:type="xs:string">
<value>%origin%/images/WaveletBig.bmp</value>
</prop>
</node>
</node>
</node>
</source>

===Footer===
Close all opened sections.

<source lang=xml>
</node>
</oor:component-data>
</source>

=UNO component package=
UNO component package is a simple ZIP file. Obviously it contains the ''Addons.xcu'' file, ''images'' directory with icons and the Python component implementation.

==Packing==
You can pack our sample package with the following command:

<source lang=bash>
zip -r Wavelet.uno.zip Addons.xcu Wavelet.py images
</source>
The final ''Wavelet.uno.zip'' package should contain these files:

<source lang=bash>
Wavelet.uno.zip
Addons.xcu
Wavelet.py
images/WaveletBig.bmp
images/WaveletSmall.bmp
</source>
'''Note:''' The ''%origin%'' is ''Wavelet.uno.zip'', thus the ''%origin%/images/WaveletBig.bmp'' points to the ''WaveletBig.bmp'' file in your ''Wavelet.uno.zip'' file.

==Installation==
You can install your UNO component with the Extension manager (somewhere in the ''Tools'' menu) or with the ''unopkg'' tool.

<source lang=bash>
/opt/openoffice.org1.9.103/program/unopkg add Wavelet.uno.zip
</source>

==Uninstallation==
You can uninstall your UNO component with the Extension manager (somewhere in the ''Tools'' menu) or with the ''unopkg'' tool.

<source lang=bash>
/opt/openoffice.org1.9.103/program/unopkg remove Wavelet.uno.zip
</source>

=Python component testing=
It's not necessary to install the Python UNO component to test it. You can connect to the running OpenOffice.org instance and test your UNO component directly.

==Code==
Append the following code at the end of the ''Wavelet.py'' file.

<source lang=python>
if __name__ == "__main__":
import os

# Start OpenOffice.org, listen for connections and open testing document
os.system( "/etc/openoffice.org-1.9/program/soffice '-accept=socket,host=localhost,port=2002;urp;' -writer ./WaveletTest.odt &" )

# Get local context info
localContext = uno.getComponentContext()
resolver = localContext.ServiceManager.createInstanceWithContext(
"com.sun.star.bridge.UnoUrlResolver", localContext )

ctx = None

# Wait until the OO.o starts and connection is established
while ctx == None:
try:
ctx = resolver.resolve(
"uno:socket,host=localhost,port=2002;urp;StarOffice.ComponentContext" )
except:
pass

# Trigger our job
wavelet = Wavelet( ctx )
wavelet.trigger( () )
</source>

==Testing==
To test your UNO component, just run your ''Wavelet.py'' in the Python interpreter.

<source lang=bash>
/opt/openoffice.org1.9.103/program/python ./Wavelet.py
</source>

==Resume==
This part does this:

starts OpenOffice.org and opens the ''WaveletTest.odt'' file

loop until the connection will be established

start your component in the running OpenOffice.org context

'''Note:''' Do not forget to remove this part before real UNO component packaging. Or comment it out.

=See also=
* [http://api.openoffice.org/docs/DevelopersGuide/Extensions/Extensions.xhtml Extensions] chapter of the Developers Guide
* Using C++ with OOo SDK : [[Constructing_Components| Constructing Component in C++]]
*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* Daniel Bölzle's [http://udk.openoffice.org/cpp/man/component_tutorial.html tutorial] : Writing a simple UNO component.
* [[UNO_component_packaging|Component with Python]]

[[Category:Uno]]
[[Category:Extensions]]

PyUNOServer

2009-12-03T06:00:00Z

Newacct:

[[image:Py-uno_128.png|right|PyUNO Logo]]
The PyUNOServer is a script that works as an XML server for OpenOffice.org Calc where it can exchange data through XML calls. This means that can get data from other apps that are XML compliant. You can download the script from [http://es.openoffice.org/files/documents/73/2929/pyUnoServer.tar.gz this mirror] since the original site seems to be down.

The zip file contains 3 files:
* '''PyUNOServerV2.py''' - The Python Script
* '''PyUNOServerV2.pyc''' - compiled version
* '''PyUNOServer.sh2''' - the script to conect to the service

The script have just 1 script called '''PyUNOServerV2.py''' however there is a faster, bytecode-compiled script. It also includes a bash script which loads the path to the openoffice.org application.

'''NOTE: This script will work on just certain distros since the location of OpenOffice.org might vary. We recomend to load the path manually.'''

This script uses the following libraries:

* '''OS''' - This module provides a more portable way of using operating system dependent functionality than importing a operating system dependent built-in module like posix or nt.
* '''UNO''' - Python UNO implementation module, this can used by python 2.3.4 '''only''' which is the python provided within openoffice.org. It provides all the interfaces from OpenOffice.org into python.
* '''SYS''' - This module provides access to some variables used or maintained by the interpreter and to functions that interact strongly with the interpreter. It is always available.
* '''time''' - This module provides various time-related functions. It is always available, but not all functions are available on all platforms. Most of the functions defined in this module call platform C library functions with the same name. It may sometimes be helpful to consult the platform documentation, because the semantics of these functions varies among platforms.
* '''logging''' - Logging is performed by calling methods on instances of the Logger class (hereafter called loggers). Each instance has a name, and they are conceptually arranged in a name space hierarchy using dots (periods) as separators.
* '''urllib''' - This module provides a high-level interface for fetching data across the World Wide Web. In particular, the urlopen() function is similar to the built-in function open(), but accepts Universal Resource Locators (URLs) instead of filenames. Some restrictions apply -- it can only open URLs for reading, and no seek operations are available.
* '''SimpleXMLRPCServer''' - The SimpleXMLRPCServer module provides a basic server framework for XML-RPC servers written in Python. Servers can either be free standing, using SimpleXMLRPCServer, or embedded in a CGI environment, using CGIXMLRPCRequestHandler.

<source lang=python>
# -*- coding: iso-8859-1 -*-
#
# pyUnoServer - version 2.0
from SimpleXMLRPCServer import SimpleXMLRPCServer, SimpleXMLRPCRequestHandler
import os
import uno
import sys
import time
import logging
import urllib

class PyUNOServer(SimpleXMLRPCServer):

def _dispatch(self, method, params):

try:
func = getattr(self, '' + method)
except:
self.logger.error("El Metodo '"+method+"' no esta soportado!")
raise Exception('method "%s" is not supported' % method)
else:
try:
ret = func(*params)
self.logger.info("Llamada: %s%s | Retorno: %s" % (method, params, ret))
return ret
except:
self.logger.info("Llamada: %s%s" % (method, params))
self.logger.error("Error: %s:%s" % sys.exc_info()[:2])

def init(self):
"""
This method starts an Openoffice session and initializes the XMLRPC server
"""

# Generate some useful constants
self.EMPTY = uno.Enum("com.sun.star.table.CellContentType", "EMPTY")
self.TEXT = uno.Enum("com.sun.star.table.CellContentType", "TEXT")
self.FORMULA = uno.Enum("com.sun.star.table.CellContentType", "FORMULA")
self.VALUE = uno.Enum("com.sun.star.table.CellContentType", "VALUE")

# Generate a Logger
self.logger = logging.getLogger('pyUnoServer')
hdlr = logging.FileHandler('./pyUnoServer.log')
formatter = logging.Formatter('%(asctime)s %(levelname)s -- %(message)s')
hdlr.setFormatter(formatter)
self.logger.addHandler(hdlr)
self.logger.setLevel(logging.INFO)

self.sessions = []
self.sessionSerial = 0

# Start Calc and grep the PID
self.PID = os.spawnlp(os.P_NOWAIT,"/usr/bin/oocalc","","-accept=socket,host=localhost,port=2002;urp;")

self.logger.info("OOCalc Iniciado con el PID %d" % self.PID)

while 1:
try:
localContext = uno.getComponentContext()
resolver = localContext.ServiceManager.createInstanceWithContext("com.sun.star.bridge.UnoUrlResolver", localContext )
smgr = resolver.resolve( "uno:socket,host=localhost,port=2002;urp;StarOffice.ServiceManager" )
remoteContext = smgr.getPropertyValue( "DefaultContext" )
self.desktop = smgr.createInstanceWithContext( "com.sun.star.frame.Desktop",remoteContext)
self.logger.info("Sistema conectado al socket de UNO")
break
except:
time.sleep(0.5)

def openSession(self, session):
"""
This method opens a new session.
Sample usage from PHP:
- $sessionString is your a session ID provided by your program):

$openSession = array( new XML_RPC_VALUE($sessionString, "string"));
$sessionID = queryXMLRPC($client, "openSession", $openSession);
return $sessionID;
"""

currentSerial = -1

for i in range(len(self.sessions)):
if self.sessions[i][0] == session:
currentSerial = i
break

if currentSerial == -1:
self.sessions.append([session,[]])
currentSerial = len(self.sessions)-1

return currentSerial

def getSessions(self):
return self.sessions

def openBook(self, session, bookPath):
"""
This method opens a new Openoffice spreadsheet book.
Sample usage from PHP:
- $sessionID is the session's ID returned by openSession()
- $path is the path to the book in the server's filesystem

$openBookQuery = array( new XML_RPC_VALUE($sessionID, "int"), new XML_RPC_VALUE($path,"string") );
$bookID = queryXMLRPC($client, "openBook", $openBookQuery);
return $bookID;
"""

currentSerial = session
bookPath = bookPath.strip()
print bookPath

exists = os.path.exists(bookPath)
if exists == False:
raise Exception('El libro %s no existe', bookPath)
else:
self.logger.info("se ha encontrado el libro!")

currentBook = -1

for i in range(len(self.sessions[currentSerial][1])):
try:

book = self.sessions[currentSerial][1][i]

bookname = book[0]
bookhandler = book[1]
bookmodtime = book[2]

if bookname == bookPath:
modtime = os.path.getmtime(bookPath)
if modtime > bookmodtime:
book[1].dispose()
self.sessions[currentSerial][1].remove(book)
else:
currentBook = i
break
except:
self.logger.error("El libro "+currentBook+" no existe!")

if currentBook < 0:
handler = self.desktop.loadComponentFromURL( "file://" + bookPath ,"_blank",0,())

if handler == None:
raise Exception('El libro no existe o tiene caracteres extraños...')

modtime = os.path.getmtime(bookPath)

estruct = [bookPath,handler,modtime]
self.sessions[currentSerial][1].append(estruct)
currentBook = len(self.sessions[currentSerial][1])-1

return currentBook

def closeBook(self, sessionID, bookID):

books = self.sessions[sessionID][1]

# Close the document. It doesn't look very elegant but thats the way is documented.
books[bookID][1].dispose()
self.sessions[sessionID][1].remove(books[bookID])

return 1

def getBookSheets(self, sessionID, bookID):
"""
This method return an array with the book's worksheets.
Sample usage from PHP:
- $sessionID is the session's ID returned by openSession()
- $bookID is the book's ID returned by openBook()

$sheetsQuery = array( new XML_RPC_VALUE($sessionID, "int"), new XML_RPC_VALUE($bookID, "int") );
$sheets = queryXMLRPC($client, "getBookSheets" , $sheetsQuery);
return $sheets;
"""

sheets = self.sessions[sessionID][1][bookID][1].getSheets().createEnumeration()

container = []
while sheets.hasMoreElements():
currentSheet = sheets.nextElement()
container.append(currentSheet.getName().encode("UTF-8"))

return container

def getCellValue (self,sheet,x,y):

cell = sheet.getCellByPosition(x,y)
cellType = cell.getType()

if cellType == self.TEXT :
data = cell.getString().encode("UTF-8")
if data == None:
return ""
return data.encode("UTF-8")

if cellType == self.FORMULA or cellType == self.VALUE :
data = cell.getValue()
if data == None:
return 0
return cell.getValue()

if cellType == self.EMPTY :
return ""

def getCell(self, session, book, sheet, x, y):
"""
This method returns the content of a cell.
Sample usage from PHP:
- $sessionID is the session's ID returned by openSession()
- $bookID is the book's ID returned by openBook()
- $sheet is the sheet's ID as returned by getBookSheets()

$query = array(
new XML_RPC_Value($sessionID, "int"),
new XML_RPC_VALUE($bookID, "int"),
new XML_RPC_VALUE($sheet, "int"),
new XML_RPC_Value($x, "int"),
new XML_RPC_Value($y, "string")
);

$result = queryXMLRPC($client, "getCell", $query);
return $result;
"""

sheetref = self.sessions[session][1][book][1].getSheets().getByIndex(sheet)
valor = self.getCellValue(sheetref,x,y)
return valor

def setCell(self,session,book,sheet,x,y,value):
"""
This method sets the content of a cell.
Sample usage from PHP:
- $sessionID is the session's ID returned by openSession()
- $bookID is the book's ID returned by openBook()
- $sheet is the sheet's ID as returned by getBookSheets()

$query = array(
new XML_RPC_Value($sessionID, "int"),
new XML_RPC_VALUE($bookID, "int"),
new XML_RPC_VALUE($sheet, "int"),
new XML_RPC_Value($x, "int"),
new XML_RPC_Value($y, "int"),
new XML_RPC_Value($value, "string")
);

$result = queryXMLRPC($client, "setCell", $query);
return $result;
"""

bookObject = self.sessions[session][1][book][1]
cell = bookObject.getSheets().getByIndex(sheet).getCellByPosition(x,y)
cell.setValue(value)
return 1

#what will change? mmm...
def massiveSetCell(self, data):
for valores in data:
session,sheetid,x,y,valor = valores.split("|")
code = self.setCell(self.trim(session),self.trim(sheetid),self.trim(x),self.trim(y),valor)
if code < 0:
return code
return 1

def getSheetPreview(self,session,book,sheet):

sheet = self.sessions[session][1][book][1].getSheets().getByIndex(sheet)
range = sheet.getCellRangeByPosition(0,0,8,23).getDataArray()
return range

def trim(self, cadena):
return cadena.strip()

server = PyUNOServer(("localhost", 8000))

server.init()
server.logger.info("Servicio Inicializado...")

try:
server.serve_forever()
except KeyboardInterrupt:
server.logger.info("Cerrando el socket...")
server.server_close()
os.kill(server.PID,1)
server.logger.info("Socket cerrado.")
</source>

==startPyUnoServer.sh2==
<source lang=bash>
#!/bin/bash
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib/openoffice/program/
export PYTHONPATH=$PYTHONPATH:/usr/lib/openoffice/program
export DISPLAY=localhost:1
echo "Logging en pyUnoServer.log"
python pyUnoServerV2.py
echo "Ciao!"
</source>

[[Category:Python]]