Apache OpenOffice Wiki - User contributions [en]

Drawing framework

2008-05-25T10:49:43Z

Holgerbrandl: fixed resource id of slidepane

==Introduction==
The drawing framework is a framework used by [[Impress]] and [[Draw]] for the coordinated activation and deactivation of resources like views, panes, and tool bars.

The primary goal in designing the drawing framework was to turn Impress and Draw into modular applications that can easily be extended by additional features.
This should be possible dynamically through extensions, not only statically at compile time. The drawing framework is accessible to extensions that are deployed via the extension manager (menu entry Tools->ExtensionManager...). This allows an extension to provide for instance a new view and to control when to show this view and in which pane to display it. This can be done in any programming language for which there is UNO API support. The [Presenter Screen|Presenter Screen extension] is one example for this.

The design of the drawing framework addresses the following goals:

*ease of use

*flexibility

*extensibility

*abstraction from underlying frameworks

The drawing framework can be seen as a resource management system, where the resources are panes, views, tool bars, commands (slots). The configuration controller synchronizes activation and deactivation of resources. It has its name from the configuration, which describes the set of active resources, i.e. the set of visible panes, views, and tool bars. Synchronization means that when two or more resources are to be activated or deactivated at the same time then the configuration controller
*orders activations and deactivations according to dependencies between resources (e.g. when a viewand a pane are to be activated then the pane is activated before the view so that the view has access to the pane),
*tries to minimize the overall time and
*reduces visual artifacts, i.e. flickering.

The drawing framework is implemented on top of and abstracts from existing framework functionality provides mostly by the SFX2 and [[Framework]] projects.

There is a [[Drawing Framework Glossary|glossary]] for the drawing framework. The API of the drawing framework is documented [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/module-ix.html here].

==Current State==
With the experience from the implementation of the [[Presenter_Screen|Presenter Screen extension]] the first incarnation of the drawing framework (that is described by older versions of this page, see history for [http://wiki.services.openoffice.org/w/index.php?title=Drawing_framework&oldid=45696 this] or older versions) has been cleaned up and simplified into its current form.

The drawing framework is used by [[Impress]] and [[Draw]] for managing views, panes, and one or two toolbars.

==Framework Design==

The following sections describe the inner structure of the drawing framework in more detail.
It starts with the set of supported resources, the ResourceIds that identify resources, and configurations that describe the set of active or requested resources.
Last comes a description of the update process that involves the actual activation and deactivation of resources.

===Resources===

The drawing framework has been desinged for four types of resources:

* Panes

* Views

* Tool Bars

* Command groups

While the first three need little explanation (the little explanation is done in the API documentation) the concept of [[Drawing Framework Glossary#Command Groups|command groups]] is not used (yet) anywhere else. A command group is a collection of commands realized by a module that implements at least the com::sun::star::frame::XDispatch interface and implements one or more commands (that to some are known as slots).

A resource is identified by a non-empty set of URLs that describe the actual resource and its dependency on other resources. One URL is called the resource URL and defines the type of the resource. A possibly empty set of anchor URLs specifies a set of resources to which the one in question is anchored. Panes for example act as containers for views and thus are their anchors: the resource URL of the left slide sorter in the left pane is <pre>private:resource/view/SlideSorter</pre>. Its anchor is the left pane with the URL being <pre>private:resource/floater/LeftImpressPane</pre>.

Here, the first part after private:resource/ specifies the type of resource:
* '''pane''' for panes
* '''view''' for views
* '''toolbar''' for tool bars
* '''command''' for command groups
The final part of the URL defines the actual resource.

===ResourceId===
Each resource is identified by an object that implements the
[http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/ResourceId.html com::sun::star::drawing::framework::ResourceId] service with its [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/XResourceId.html com::sun::star::drawing::framework::XResourceId] interface. The XResourceId interface gives access to a set of URLs which specify the resource. There is one URL returned by the getResourceURL() function that defines the type of the resource. A possibly empty set of URLs returned by getAnchorURLs() specifies the anchor resource.

Each resource in a configuration has to have a unique resource id. Two resource ids may have the same resource URLs but then their anchors must not be the same. An example for this would be the slide sorter being shown in two different panes. Alternatively two resource may have the same anchor but then must not have the same resource URL. An example for this is the view tab bar and the view in the center pane. The anchor of both is the center pane.

Lets take the slide sorter as an example for this. In the left pane, the slide sorter bar is described by the ResourceId
<pre>private:resource/floater/LeftImpressPane, private:resource/view/SlideSorter</pre>
The slide sorter view in the center pane id described by the ResourceId
<pre>private:resource/pane/CenterPane, private:resource/view/SlideSorter</pre>

Panes are the typical anchor resources. They do not have an anchor, therefore getAnchorURLs() returns an empty list for them. An example for an anchor that is not a pane is the view tab bar. It is linked to the center pane. It is the anchor for its tabs that each represent one view that may by displayed in the center pane. The resource ids of the two left most tabs are for example
<pre>private:resource/pane/CenterPane, private:resource/toolbar/ViewTabBar, private:resource/view/ImpressView
private:resource/pane/CenterPane, private:resource/toolbar/ViewTabBar, private:resource/view/OutlineView</pre>

The ResourceId service provides four functions for creating ResourceId objects. These are createEmpty() and create() for creating an empty resource id and one that has no anchor. The createWithAnchor() variant creates a resource whose anchor is given as ResourceId object. When the later is empty then the resulting resource could have been created with create(). Finally createWithAnchorURL takes two URLs, one for the actual resource and one for its anchor. These four variants cover the most common usages but it may be extended in the future (note drawing framework API is not yet marked as published and may be modified.)

===Known Resources===
A list of known resources can be found [[Drawing Framework Resources|here]].

===Configuration===

A [[Drawing Framework Glossary#Configuration|configuration]] describes a set
of resources. There are two important configurations, which ideally are
identical:

*The [[Drawing Framework Glossary#Current Configuration|current configuration]] describes the set of currently active resources. The term ''active'' can mean different things for different types of resources. For panes, views, and tool bars it means that they are visible. For a command group it means that that group is ready to process incoming slot calls.

*The [[Drawing Framework Glossary#Requested Configuration|requested configuration]] describes the set of resources that have been requested to be active either directly by the user or by the application in response to some user input.

Usually the two configurations differ only temporarily after a
new request for the activation or deactivation of a resource has been made
but not yet been processed. Eventually the current configuration is updated to
reflect the requested configuration. There may, however, be circumstances,
that do not allow a resource to be activated or (less likely) to be deactivated.
One reason for this is that some resources are created asynchronously and
become available only after a little time.

See the [[Drawing Framework Glossary#Configuration|configuration]] glossary
entry for examples.

It is possible obtain a copy of the requested configuration and restore it
later. This allows to undo temporary changes. For example, the in-place
slide show uses this feature to temporarily hide the side panes and to
restore them when the show ends.

===Three layer design===

The drawing framework consists of controllers, factories, and application
logic modules. These are located on three layers. The assignment to the
different layers depends on the knowledge about different aspects of the
resource management:

;Application Layer:The [[Drawing Framework Glossary#Application Layer|application layer]] controls '''when''' to activate or deactivate a resource. This layer contains the application logic. For example the Impress application uses a module that is responsible for activating or deactivating the slide sorter bar depending on the view that is displayed in the center pane.

;Synchronization Layer:The [[Drawing Framework Glossary#Synchronization Layer|synchronization layer]] uses the XConfigurationController to '''synchronize''' the requests from the application layer with the resource controllers in the resource layer. It has no detailed knowledge about individual resources nor about the application logic.

;Resource Layer:The resource factories in the [[Drawing Framework Glossary#Resource Layer|resource layer]] know '''how''' to activate or deactivate resources. The XResourceControllers are called by the XConfigurationController to update the the current configuration so that it looks like the requested configuration.

[[image:DrawingFrameworkDesign.png|The different parts of the drawing framework are organized in three layers]]

The image illustrates the three layer design for the Impress application. The ImpressModule is created by the ImpressViewShell when the user creates a new Impress document. The ImpressModule creates the other modules in the application layer that control different aspect of the application. For example they watch for user input and switch to different views in ther center pane accordingly.

The modules in the application layer communicate with the XConfgurationController in the synchronization layer to make requests for the activation or deactivation of panes and views. The XConfigurationController modifies the RequestedConfiguration accordingly.

Eventually the CurrentConfiguration is updated. The XConfigurationController then determines the order in which to activate and deactivate resources and calls the resource factories in that order to create resources that are activated or to release resources that are deactivated.

Resource factories can implement a cache to store deactivated resources. Some resources like the slide sorter bar are activated and deactivated frequently. Caching it may speed this up.

===Two phase updates===

The drawing framework negotiates between modules implementing application
logic that want to show or hide a resource on one side and the resource
factories on the other side. The negotiation process is iterative: the
activation request of a resource made by one application logic module may
cause the activation request of another resource made by a second module.
For example, when the user switches the view in the center pane to the
outline view, then the task pane is deactivated.

The negation process is split into two phases, one
for collecting a list of all the necessary changes and the second for
updating the GUI to reflect these changes.

;Negotiation Phase: The negotiation phase is triggered by the initial request, for example the switch of the view in the center pane. In this phase only the the requested configuration is modified. The requested change is stored in the requested configuration and then is broadcasted. Listeners may react by making further requests for activation or deactivation of other resources. These are again stored in the requested configuration and broadcasted and may lead to even more requests. All requests are put into a queue which is processed until there are no more pending requests.

;Update Phase:When all requests have been processed and the the requested configuration describes a new consistent state of the GUI then the second, the '''update phase''' is started. In this phase only the current configuration is modified.
:That is, the requested configuration is not modified directly in this phase. The application can of course request the activation or deactivation of resources. Therefore, in the update phase a copy of the requested configuration is used which remains unchanged during the update.
:The different resource factories are asked to create or relase resources so that eventually the current configuration looks like the requested configuration. Every activation and deactivation is broadcasted like the requests for the activations and deactivations where.

It is the task of the configuration controller to order the activations and deactivations according to dependencies between affected resources and to optimize the update
phase with respect to time and visual artifacts/flickering.

==Extensibility==
The drawing framework is designed to be extensible with regard to the set of known resources and to the application logic.

For a new resource you have to provide a factory and register it at the configuration manager. An example could be a new view or a new tool bar.

For a new piece of application logic add a listener to the configuration controller and react to activations or deactivations of relevant resources.

==Implementation and Examples==
The examples in the following sections show how to use the drawing framework to request and access resources and how to react to changes of the current configuration. Note that the code is C++ like pseudo code that can not be compiled as is.

===FrameworkHelper===
The ::sd::framework::FrameworkHelper class provides two things
* the most frequently used resource URLs so that you do not have to remember them, have trouble with resource allocation, or are able to misspell resource names, and
* some helper functions that simplify the work with the UNO based drawing framework from inside core code.
The FrameworkHelper is a multi singleton. Its Instance() method returns for a ViewShellBase object the associated FrameworkHelper object. The functions provided cover
* mapping between sd::ViewShell::ShellType and view resource URL,
* obtain view objects for their URLs or ResourceIds,
* making requests for the activation or deactivation of resources,
* locking configuration updates,
* waiting for certain events to make asynchronous requests synchronous.

One example for that is a request for the activation of the slide sorter bar:
<pre>
FrameworkHelper::Instance(GetViewShellBase()).RequestView(
ResourceId::createWithAnchorURL(
aComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
</pre>

===Drawing Framework API===
The following subsections provide a short introduction of the UNO API of the drawing framework. For details please refer to the API documentation (not yet available.)

====Getting Access to the Drawing Framework====
Using the UNO API of the drawing framework to access active resources or to request the activation or deactivation of resources starts with the [http://api.openoffice.org/docs/common/ref/com/sun/star/frame/XController.html XController] of an [[Impress]] or a [[Draw]] document. From this you can obtain the [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/XControllerManager.html XControllerManager] and from that the [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/XConfigurationController.html XConfigurationController]. The XConfigurationController is the main access point for making requests and for accessing resources.
<pre>
using ::com::sun::star::uno;
using ::com::sun::star::frame;
using ::com::sun::star::drawing::framework;

Reference<XController> xController; // This is regarded as given.
Reference<XComponentContext> xComponentContext; // This also is regarded as given.

Reference<XControllerManager> xCM (xController, UNO_QUERY_THROW);
Reference<XConfigurationController> xCC (xCM->getConfigurationController());
</pre>

====Requesting a Resource Activation====
Once you have obtained access to the XConfigurationController, making requests to activate or deactivate resources is simple. The following code requests the activation of the slide sorter bar:
<pre>
xCC->requestResourceActivation(
ResourceId::createWithAnchorURL(
xComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
</pre>
If you compare this to the code bove that uses the FrameworkHelper to accomplish
the same thing then you see, that the FrameworkHelper only hides the
connection from the ViewShellBase to the XConfigurationController. The rest
of the call is basically the same.

However, the drawing framework does not provide too many automatisms on this
layer (that is the task of the modules in the application layer) so the pane
in which to show the slide sorter has to be requested as well.
<pre>
xCC->requestResourceActivation(
ResourceId::create(
xComponentContext,
FrameworkHelper::msLeftImpressPaneURL));
</pre>
Note the use of ResourceId::create() instead of ResourceId::createWithAnchorURL(). This is because a pane, in contrast to the view that was requested earlier, is not bound to any other resource.

The two requests should be executed together. An intermediate update of the
current configuration is not necessary and would lead to an annoying display
of an empty window before the slide sorter bar is properly shown. The
probability that this happens is low but not zero. Therefore it is good
practice to lock the XConfigurationController while the two requests are
made. This prevents unwanted updates. You can call the lock() and unlock()
methods directly but it is safer to use the ConfigurationController::Lock
inner class to do that. Adding this and bringing the two requests into the
logical order you get
<pre>
{
::sd::framework::ConfigurationController::Lock(xCC);
xCC->requestResourceActivation(
ResourceId::create(
aComponentContext,
FrameworkHelper::msLeftImpressPaneURL));
xCC->requestResourceActivation(
ResourceId::createWithAnchorURL(
aComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
}
</pre>

====Accessing a Resource====
If you want to access an active resource directly then you have to ask the
XConfigurationController for it. Suppose you are interested in accessing the window of the left
pane that shows the slide sorter bar:
<pre>
Reference<XPane> xPane (xCC->getResource(
ResourceId::create(
aComponentContext,
FrameworkHelper::msLeftImpressPaneURL),
UNO_QUERY);
if (xPane.is())
{
Reference<XWindow> xWindow (xPane->getWindow());
if (xWindow->is())
{
// Do something with the window.
}
}
</pre>

====Reacting to Modifications of the Configuration====
When you want to implement application logic then you have to react to user input by requesting changes to the current configuration. User input can come in many ways. Here we cover only the indirect way of (requested) changes of the current configuration made by others.

The following code turns on the slide sorter bar when the center pane is switched to
the edit view, outline view, or notes view and turns it off for all other views. The drawing framework contains a module in the application layer that does essentially the same.
<pre>
class SlideSorterBarManager : public XConfigurationChangeListener {
public:
Reference<XConfigurationController> mxCC;

void SlideSorterBarManager (const Reference<XConfigurationController>& rxCC)
: mxCC(rxCC)
{
Reference<XConfigurationControllerBroadcaster> xCCB (mxCC, UNO_QUERY);
xCCB->addConfigurationChangeListener(
this,
FramworkHelper::msResourceActivationRequestEvent,
Any());
}

virtual void notifyConfigurationChange (const ConfigurationChangeEvent& rEvent)
{
if (rEvent.Type.equals(FrameworkHelper::msResourceActivationRequestEvent))
{
if (rEvent.ResourceId.is())
&& rEvent.ResourceId->isBoundToURL(FrameworkHelper::msCenterPaneURL,DIRECT))
{
// A resource has been requested for the center pane.
::rtl::OUString sResourceURL (rEvent.ResourceId->getResourceURL());
if (sResourceURL.equals(FrameworkHelper::msImpressViewURL)
|| sResourceURL.equals(FrameworkHelper::msOutlineViewURL)
|| sResourceURL.equals(FrameworkHelper::msNotesViewURL))
{
// Show the slide sorter bar.
xCC->requestResourceActivation(
ResourceId::create(
aComponentContext,
FrameworkHelper::msLeftImpressPaneURL));
xCC->requestResourceActivation(
ResourceId::createWithAnchorURL(
aComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
}
else
{
// Hide the slide sorter bar for the handout view, the slide
// sorter view, and all views that where not handled above.
mxCC->requestResourceDeactivation(
ResourceId::createWithAnchorURL(
aComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
}
}
}
};
</pre>
There are three things to note in this code:
# The first '''if''' statement in the notifyConfigurationChange() method is not really necessary because the listener is registered only for this one event type and thus will not be called for other event types.
# There is no update lock surrounding the activation requests for the slide sorter bar. This is not necessary here, because the listener is only called during the negotiation phase. During this whole phase the update is locked.
# There is only one deactivation request, the one for the view. The request for the pane is missing. This is because there might be other resources bound to the pane. However, this is one of a few places where an automatism is active: when there are no resources bound to a pane when the negotiation phase ends, then the pane is deactivated.

====Providing a New Resource====
To provide a new resource, say a SingleColorView that fills a window with a
single color, you have to
*Provide the actual view
*Provide a factory that creates a view object for a given XPane object
*Register the factory
*Request the new view

A view has to support the [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/XView.html css::drawing::framework::XView] interface which is
derived from the XResource interface. Both interfaces are extremely simple
because the drawing framework does not need to know much about its
resources.

The knowledge is concentrated only in the factory and of course in the
implementation of the new view. Both a new resource and its factory are
typically deployed together so they can use private and implementation
language dependent means to communicate with each other and share information.

The factory is given a ResourceId when asked for a new resource object. For
the SingleColorView the ResourceId is used to look up the corresponding
XPane object from which the XWindow reference is obtained. For the standard
panes the XPane object supports the XUnoTunnel interface which gives access
to the VCL Window pointer, but that is not used here.

<pre>
class SingleColorViewFactory : XResourceFactory
{
public:
virtual Reference<XView> createResource (
const Reference<XResourceId>& rxViewId)
{
Reference<XResource> xView;

// Get the XWindow object fort the AnchorURL of the given ResourceId.
Reference<XControllerManager> xCM (xController, UNO_QUERY_THROW);
Reference<XConfigurationController> xCC (xCM->getConfigurationController());
Reference<XPane> xPane (xCC->getResource(rxViewId->getAnchor()), UNO_QUERY);
if (xPane.is())
{
// Create the view for the XWindow object.
Reference<XWindow> xWindow (xPane->getWindow());
if (xWindow.is())
xView = new SingleColorView(rxViewId, xWindow);
}

return xView;
}

virtual void releaseView (
const Reference<XResource>& rxView)
{
// Do nothing. When the caller releases its reference to the view,
// then the view will be destroyed.
}
};
</pre>
<pre>
class SingleColorView : drawing::framework::XView, awt::XPaintListener
{
public:
SingleColorView(
const Reference<XResourceId>& rxViewId,
const Reference<XWindow>& rxWindow)
: mxViewId(rxViewId)
{
rxWindow->addPaintListener(this);
}

virtual ResourceId getResourceId (void)
{
return maId;
}

virtual void windowPaint (const awt::PaintEvent& rEvent)
{
// Paint the area specified by the event.
}

private:
Reference<XResourceId> mxViewId;
};
</pre>
The factory can be registered in two ways.
#Dynamically by calling XViewController::addViewFactory()
#Statically by adding an entry to the configuration.

For the latter you have to provide a UNO service for the view factory, say com.sun.star.drawing.framework.SingleColorViewFactory. With
this, merge the following entry into the Impress.xcu file.
<pre>
<node oor:name="MultiPaneGUI">
<node oor:name="Framework">
<node oor:name="ResourceFactories">
<node oor:name="F0" oor:op="replace">
<prop oor:name="ServiceName">
<value>com.sun.star.drawing.framework.SingleColorViewFactory</value>
</prop>
<node oor:name="ResourceList">
<node oor:name="R0" oor:op="replace">
<prop oor:name="URL">
<value>private:resource/view/SingleColorView</value>
</prop>
</node>
</node>
</node>
</node>
</node>
</node>
</pre>
All what remains to be done is to request the view. To show it in the right
pane, instead of the task panel, make this call:
<pre>
xCC->requestResourceActivation(
ResourceId::createWithAnchorURL(
xComponentContext,
::rtl::OUString::createFromAscii("private:resource/view/SingleColorView"),
FameworkHelper::msRightPaneURL));
</pre>

[[Category:Impress]]

Drawing framework

2008-05-25T10:48:55Z

Holgerbrandl: fixed resource id of slidepane

==Introduction==
The drawing framework is a framework used by [[Impress]] and [[Draw]] for the coordinated activation and deactivation of resources like views, panes, and tool bars.

The primary goal in designing the drawing framework was to turn Impress and Draw into modular applications that can easily be extended by additional features.
This should be possible dynamically through extensions, not only statically at compile time. The drawing framework is accessible to extensions that are deployed via the extension manager (menu entry Tools->ExtensionManager...). This allows an extension to provide for instance a new view and to control when to show this view and in which pane to display it. This can be done in any programming language for which there is UNO API support. The [Presenter Screen|Presenter Screen extension] is one example for this.

The design of the drawing framework addresses the following goals:

*ease of use

*flexibility

*extensibility

*abstraction from underlying frameworks

The drawing framework can be seen as a resource management system, where the resources are panes, views, tool bars, commands (slots). The configuration controller synchronizes activation and deactivation of resources. It has its name from the configuration, which describes the set of active resources, i.e. the set of visible panes, views, and tool bars. Synchronization means that when two or more resources are to be activated or deactivated at the same time then the configuration controller
*orders activations and deactivations according to dependencies between resources (e.g. when a viewand a pane are to be activated then the pane is activated before the view so that the view has access to the pane),
*tries to minimize the overall time and
*reduces visual artifacts, i.e. flickering.

The drawing framework is implemented on top of and abstracts from existing framework functionality provides mostly by the SFX2 and [[Framework]] projects.

There is a [[Drawing Framework Glossary|glossary]] for the drawing framework. The API of the drawing framework is documented [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/module-ix.html here].

==Current State==
With the experience from the implementation of the [[Presenter_Screen|Presenter Screen extension]] the first incarnation of the drawing framework (that is described by older versions of this page, see history for [http://wiki.services.openoffice.org/w/index.php?title=Drawing_framework&oldid=45696 this] or older versions) has been cleaned up and simplified into its current form.

The drawing framework is used by [[Impress]] and [[Draw]] for managing views, panes, and one or two toolbars.

==Framework Design==

The following sections describe the inner structure of the drawing framework in more detail.
It starts with the set of supported resources, the ResourceIds that identify resources, and configurations that describe the set of active or requested resources.
Last comes a description of the update process that involves the actual activation and deactivation of resources.

===Resources===

The drawing framework has been desinged for four types of resources:

* Panes

* Views

* Tool Bars

* Command groups

While the first three need little explanation (the little explanation is done in the API documentation) the concept of [[Drawing Framework Glossary#Command Groups|command groups]] is not used (yet) anywhere else. A command group is a collection of commands realized by a module that implements at least the com::sun::star::frame::XDispatch interface and implements one or more commands (that to some are known as slots).

A resource is identified by a non-empty set of URLs that describe the actual resource and its dependency on other resources. One URL is called the resource URL and defines the type of the resource. A possibly empty set of anchor URLs specifies a set of resources to which the one in question is anchored. Panes for example act as containers for views and thus are their anchors: the resource URL of the left slide sorter in the left pane is <pre>private:resource/view/SlideSorter</pre>. Its anchor is the left pane with the URL being <pre>private:resource/floater/LeftImpressPane</pre>.

Here, the first part after private:resource/ specifies the type of resource:
* '''pane''' for panes
* '''view''' for views
* '''toolbar''' for tool bars
* '''command''' for command groups
The final part of the URL defines the actual resource.

===ResourceId===
Each resource is identified by an object that implements the
[http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/ResourceId.html com::sun::star::drawing::framework::ResourceId] service with its [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/XResourceId.html com::sun::star::drawing::framework::XResourceId] interface. The XResourceId interface gives access to a set of URLs which specify the resource. There is one URL returned by the getResourceURL() function that defines the type of the resource. A possibly empty set of URLs returned by getAnchorURLs() specifies the anchor resource.

Each resource in a configuration has to have a unique resource id. Two resource ids may have the same resource URLs but then their anchors must not be the same. An example for this would be the slide sorter being shown in two different panes. Alternatively two resource may have the same anchor but then must not have the same resource URL. An example for this is the view tab bar and the view in the center pane. The anchor of both is the center pane.

Lets take the slide sorter as an example for this. In the left pane, the slide sorter bar is described by the ResourceId
<pre>private:resource/pane/LeftImpressPane, private:resource/view/SlideSorter</pre>
The slide sorter view in the center pane id described by the ResourceId
<pre>private:resource/pane/CenterPane, private:resource/view/SlideSorter</pre>

Panes are the typical anchor resources. They do not have an anchor, therefore getAnchorURLs() returns an empty list for them. An example for an anchor that is not a pane is the view tab bar. It is linked to the center pane. It is the anchor for its tabs that each represent one view that may by displayed in the center pane. The resource ids of the two left most tabs are for example
<pre>private:resource/pane/CenterPane, private:resource/toolbar/ViewTabBar, private:resource/view/ImpressView
private:resource/pane/CenterPane, private:resource/toolbar/ViewTabBar, private:resource/view/OutlineView</pre>

The ResourceId service provides four functions for creating ResourceId objects. These are createEmpty() and create() for creating an empty resource id and one that has no anchor. The createWithAnchor() variant creates a resource whose anchor is given as ResourceId object. When the later is empty then the resulting resource could have been created with create(). Finally createWithAnchorURL takes two URLs, one for the actual resource and one for its anchor. These four variants cover the most common usages but it may be extended in the future (note drawing framework API is not yet marked as published and may be modified.)

===Known Resources===
A list of known resources can be found [[Drawing Framework Resources|here]].

===Configuration===

A [[Drawing Framework Glossary#Configuration|configuration]] describes a set
of resources. There are two important configurations, which ideally are
identical:

*The [[Drawing Framework Glossary#Current Configuration|current configuration]] describes the set of currently active resources. The term ''active'' can mean different things for different types of resources. For panes, views, and tool bars it means that they are visible. For a command group it means that that group is ready to process incoming slot calls.

*The [[Drawing Framework Glossary#Requested Configuration|requested configuration]] describes the set of resources that have been requested to be active either directly by the user or by the application in response to some user input.

Usually the two configurations differ only temporarily after a
new request for the activation or deactivation of a resource has been made
but not yet been processed. Eventually the current configuration is updated to
reflect the requested configuration. There may, however, be circumstances,
that do not allow a resource to be activated or (less likely) to be deactivated.
One reason for this is that some resources are created asynchronously and
become available only after a little time.

See the [[Drawing Framework Glossary#Configuration|configuration]] glossary
entry for examples.

It is possible obtain a copy of the requested configuration and restore it
later. This allows to undo temporary changes. For example, the in-place
slide show uses this feature to temporarily hide the side panes and to
restore them when the show ends.

===Three layer design===

The drawing framework consists of controllers, factories, and application
logic modules. These are located on three layers. The assignment to the
different layers depends on the knowledge about different aspects of the
resource management:

;Application Layer:The [[Drawing Framework Glossary#Application Layer|application layer]] controls '''when''' to activate or deactivate a resource. This layer contains the application logic. For example the Impress application uses a module that is responsible for activating or deactivating the slide sorter bar depending on the view that is displayed in the center pane.

;Synchronization Layer:The [[Drawing Framework Glossary#Synchronization Layer|synchronization layer]] uses the XConfigurationController to '''synchronize''' the requests from the application layer with the resource controllers in the resource layer. It has no detailed knowledge about individual resources nor about the application logic.

;Resource Layer:The resource factories in the [[Drawing Framework Glossary#Resource Layer|resource layer]] know '''how''' to activate or deactivate resources. The XResourceControllers are called by the XConfigurationController to update the the current configuration so that it looks like the requested configuration.

[[image:DrawingFrameworkDesign.png|The different parts of the drawing framework are organized in three layers]]

The image illustrates the three layer design for the Impress application. The ImpressModule is created by the ImpressViewShell when the user creates a new Impress document. The ImpressModule creates the other modules in the application layer that control different aspect of the application. For example they watch for user input and switch to different views in ther center pane accordingly.

The modules in the application layer communicate with the XConfgurationController in the synchronization layer to make requests for the activation or deactivation of panes and views. The XConfigurationController modifies the RequestedConfiguration accordingly.

Eventually the CurrentConfiguration is updated. The XConfigurationController then determines the order in which to activate and deactivate resources and calls the resource factories in that order to create resources that are activated or to release resources that are deactivated.

Resource factories can implement a cache to store deactivated resources. Some resources like the slide sorter bar are activated and deactivated frequently. Caching it may speed this up.

===Two phase updates===

The drawing framework negotiates between modules implementing application
logic that want to show or hide a resource on one side and the resource
factories on the other side. The negotiation process is iterative: the
activation request of a resource made by one application logic module may
cause the activation request of another resource made by a second module.
For example, when the user switches the view in the center pane to the
outline view, then the task pane is deactivated.

The negation process is split into two phases, one
for collecting a list of all the necessary changes and the second for
updating the GUI to reflect these changes.

;Negotiation Phase: The negotiation phase is triggered by the initial request, for example the switch of the view in the center pane. In this phase only the the requested configuration is modified. The requested change is stored in the requested configuration and then is broadcasted. Listeners may react by making further requests for activation or deactivation of other resources. These are again stored in the requested configuration and broadcasted and may lead to even more requests. All requests are put into a queue which is processed until there are no more pending requests.

;Update Phase:When all requests have been processed and the the requested configuration describes a new consistent state of the GUI then the second, the '''update phase''' is started. In this phase only the current configuration is modified.
:That is, the requested configuration is not modified directly in this phase. The application can of course request the activation or deactivation of resources. Therefore, in the update phase a copy of the requested configuration is used which remains unchanged during the update.
:The different resource factories are asked to create or relase resources so that eventually the current configuration looks like the requested configuration. Every activation and deactivation is broadcasted like the requests for the activations and deactivations where.

It is the task of the configuration controller to order the activations and deactivations according to dependencies between affected resources and to optimize the update
phase with respect to time and visual artifacts/flickering.

==Extensibility==
The drawing framework is designed to be extensible with regard to the set of known resources and to the application logic.

For a new resource you have to provide a factory and register it at the configuration manager. An example could be a new view or a new tool bar.

For a new piece of application logic add a listener to the configuration controller and react to activations or deactivations of relevant resources.

==Implementation and Examples==
The examples in the following sections show how to use the drawing framework to request and access resources and how to react to changes of the current configuration. Note that the code is C++ like pseudo code that can not be compiled as is.

===FrameworkHelper===
The ::sd::framework::FrameworkHelper class provides two things
* the most frequently used resource URLs so that you do not have to remember them, have trouble with resource allocation, or are able to misspell resource names, and
* some helper functions that simplify the work with the UNO based drawing framework from inside core code.
The FrameworkHelper is a multi singleton. Its Instance() method returns for a ViewShellBase object the associated FrameworkHelper object. The functions provided cover
* mapping between sd::ViewShell::ShellType and view resource URL,
* obtain view objects for their URLs or ResourceIds,
* making requests for the activation or deactivation of resources,
* locking configuration updates,
* waiting for certain events to make asynchronous requests synchronous.

One example for that is a request for the activation of the slide sorter bar:
<pre>
FrameworkHelper::Instance(GetViewShellBase()).RequestView(
ResourceId::createWithAnchorURL(
aComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
</pre>

===Drawing Framework API===
The following subsections provide a short introduction of the UNO API of the drawing framework. For details please refer to the API documentation (not yet available.)

====Getting Access to the Drawing Framework====
Using the UNO API of the drawing framework to access active resources or to request the activation or deactivation of resources starts with the [http://api.openoffice.org/docs/common/ref/com/sun/star/frame/XController.html XController] of an [[Impress]] or a [[Draw]] document. From this you can obtain the [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/XControllerManager.html XControllerManager] and from that the [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/XConfigurationController.html XConfigurationController]. The XConfigurationController is the main access point for making requests and for accessing resources.
<pre>
using ::com::sun::star::uno;
using ::com::sun::star::frame;
using ::com::sun::star::drawing::framework;

Reference<XController> xController; // This is regarded as given.
Reference<XComponentContext> xComponentContext; // This also is regarded as given.

Reference<XControllerManager> xCM (xController, UNO_QUERY_THROW);
Reference<XConfigurationController> xCC (xCM->getConfigurationController());
</pre>

====Requesting a Resource Activation====
Once you have obtained access to the XConfigurationController, making requests to activate or deactivate resources is simple. The following code requests the activation of the slide sorter bar:
<pre>
xCC->requestResourceActivation(
ResourceId::createWithAnchorURL(
xComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
</pre>
If you compare this to the code bove that uses the FrameworkHelper to accomplish
the same thing then you see, that the FrameworkHelper only hides the
connection from the ViewShellBase to the XConfigurationController. The rest
of the call is basically the same.

However, the drawing framework does not provide too many automatisms on this
layer (that is the task of the modules in the application layer) so the pane
in which to show the slide sorter has to be requested as well.
<pre>
xCC->requestResourceActivation(
ResourceId::create(
xComponentContext,
FrameworkHelper::msLeftImpressPaneURL));
</pre>
Note the use of ResourceId::create() instead of ResourceId::createWithAnchorURL(). This is because a pane, in contrast to the view that was requested earlier, is not bound to any other resource.

The two requests should be executed together. An intermediate update of the
current configuration is not necessary and would lead to an annoying display
of an empty window before the slide sorter bar is properly shown. The
probability that this happens is low but not zero. Therefore it is good
practice to lock the XConfigurationController while the two requests are
made. This prevents unwanted updates. You can call the lock() and unlock()
methods directly but it is safer to use the ConfigurationController::Lock
inner class to do that. Adding this and bringing the two requests into the
logical order you get
<pre>
{
::sd::framework::ConfigurationController::Lock(xCC);
xCC->requestResourceActivation(
ResourceId::create(
aComponentContext,
FrameworkHelper::msLeftImpressPaneURL));
xCC->requestResourceActivation(
ResourceId::createWithAnchorURL(
aComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
}
</pre>

====Accessing a Resource====
If you want to access an active resource directly then you have to ask the
XConfigurationController for it. Suppose you are interested in accessing the window of the left
pane that shows the slide sorter bar:
<pre>
Reference<XPane> xPane (xCC->getResource(
ResourceId::create(
aComponentContext,
FrameworkHelper::msLeftImpressPaneURL),
UNO_QUERY);
if (xPane.is())
{
Reference<XWindow> xWindow (xPane->getWindow());
if (xWindow->is())
{
// Do something with the window.
}
}
</pre>

====Reacting to Modifications of the Configuration====
When you want to implement application logic then you have to react to user input by requesting changes to the current configuration. User input can come in many ways. Here we cover only the indirect way of (requested) changes of the current configuration made by others.

The following code turns on the slide sorter bar when the center pane is switched to
the edit view, outline view, or notes view and turns it off for all other views. The drawing framework contains a module in the application layer that does essentially the same.
<pre>
class SlideSorterBarManager : public XConfigurationChangeListener {
public:
Reference<XConfigurationController> mxCC;

void SlideSorterBarManager (const Reference<XConfigurationController>& rxCC)
: mxCC(rxCC)
{
Reference<XConfigurationControllerBroadcaster> xCCB (mxCC, UNO_QUERY);
xCCB->addConfigurationChangeListener(
this,
FramworkHelper::msResourceActivationRequestEvent,
Any());
}

virtual void notifyConfigurationChange (const ConfigurationChangeEvent& rEvent)
{
if (rEvent.Type.equals(FrameworkHelper::msResourceActivationRequestEvent))
{
if (rEvent.ResourceId.is())
&& rEvent.ResourceId->isBoundToURL(FrameworkHelper::msCenterPaneURL,DIRECT))
{
// A resource has been requested for the center pane.
::rtl::OUString sResourceURL (rEvent.ResourceId->getResourceURL());
if (sResourceURL.equals(FrameworkHelper::msImpressViewURL)
|| sResourceURL.equals(FrameworkHelper::msOutlineViewURL)
|| sResourceURL.equals(FrameworkHelper::msNotesViewURL))
{
// Show the slide sorter bar.
xCC->requestResourceActivation(
ResourceId::create(
aComponentContext,
FrameworkHelper::msLeftImpressPaneURL));
xCC->requestResourceActivation(
ResourceId::createWithAnchorURL(
aComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
}
else
{
// Hide the slide sorter bar for the handout view, the slide
// sorter view, and all views that where not handled above.
mxCC->requestResourceDeactivation(
ResourceId::createWithAnchorURL(
aComponentContext,
FrameworkHelper::msSlideSorterURL,
FrameworkHelper::msLeftImpressPaneURL));
}
}
}
};
</pre>
There are three things to note in this code:
# The first '''if''' statement in the notifyConfigurationChange() method is not really necessary because the listener is registered only for this one event type and thus will not be called for other event types.
# There is no update lock surrounding the activation requests for the slide sorter bar. This is not necessary here, because the listener is only called during the negotiation phase. During this whole phase the update is locked.
# There is only one deactivation request, the one for the view. The request for the pane is missing. This is because there might be other resources bound to the pane. However, this is one of a few places where an automatism is active: when there are no resources bound to a pane when the negotiation phase ends, then the pane is deactivated.

====Providing a New Resource====
To provide a new resource, say a SingleColorView that fills a window with a
single color, you have to
*Provide the actual view
*Provide a factory that creates a view object for a given XPane object
*Register the factory
*Request the new view

A view has to support the [http://api.openoffice.org/docs/common/ref/com/sun/star/drawing/framework/XView.html css::drawing::framework::XView] interface which is
derived from the XResource interface. Both interfaces are extremely simple
because the drawing framework does not need to know much about its
resources.

The knowledge is concentrated only in the factory and of course in the
implementation of the new view. Both a new resource and its factory are
typically deployed together so they can use private and implementation
language dependent means to communicate with each other and share information.

The factory is given a ResourceId when asked for a new resource object. For
the SingleColorView the ResourceId is used to look up the corresponding
XPane object from which the XWindow reference is obtained. For the standard
panes the XPane object supports the XUnoTunnel interface which gives access
to the VCL Window pointer, but that is not used here.

<pre>
class SingleColorViewFactory : XResourceFactory
{
public:
virtual Reference<XView> createResource (
const Reference<XResourceId>& rxViewId)
{
Reference<XResource> xView;

// Get the XWindow object fort the AnchorURL of the given ResourceId.
Reference<XControllerManager> xCM (xController, UNO_QUERY_THROW);
Reference<XConfigurationController> xCC (xCM->getConfigurationController());
Reference<XPane> xPane (xCC->getResource(rxViewId->getAnchor()), UNO_QUERY);
if (xPane.is())
{
// Create the view for the XWindow object.
Reference<XWindow> xWindow (xPane->getWindow());
if (xWindow.is())
xView = new SingleColorView(rxViewId, xWindow);
}

return xView;
}

virtual void releaseView (
const Reference<XResource>& rxView)
{
// Do nothing. When the caller releases its reference to the view,
// then the view will be destroyed.
}
};
</pre>
<pre>
class SingleColorView : drawing::framework::XView, awt::XPaintListener
{
public:
SingleColorView(
const Reference<XResourceId>& rxViewId,
const Reference<XWindow>& rxWindow)
: mxViewId(rxViewId)
{
rxWindow->addPaintListener(this);
}

virtual ResourceId getResourceId (void)
{
return maId;
}

virtual void windowPaint (const awt::PaintEvent& rEvent)
{
// Paint the area specified by the event.
}

private:
Reference<XResourceId> mxViewId;
};
</pre>
The factory can be registered in two ways.
#Dynamically by calling XViewController::addViewFactory()
#Statically by adding an entry to the configuration.

For the latter you have to provide a UNO service for the view factory, say com.sun.star.drawing.framework.SingleColorViewFactory. With
this, merge the following entry into the Impress.xcu file.
<pre>
<node oor:name="MultiPaneGUI">
<node oor:name="Framework">
<node oor:name="ResourceFactories">
<node oor:name="F0" oor:op="replace">
<prop oor:name="ServiceName">
<value>com.sun.star.drawing.framework.SingleColorViewFactory</value>
</prop>
<node oor:name="ResourceList">
<node oor:name="R0" oor:op="replace">
<prop oor:name="URL">
<value>private:resource/view/SingleColorView</value>
</prop>
</node>
</node>
</node>
</node>
</node>
</node>
</pre>
All what remains to be done is to request the view. To show it in the right
pane, instead of the task panel, make this call:
<pre>
xCC->requestResourceActivation(
ResourceId::createWithAnchorURL(
xComponentContext,
::rtl::OUString::createFromAscii("private:resource/view/SingleColorView"),
FameworkHelper::msRightPaneURL));
</pre>

[[Category:Impress]]

Documentation/DevGuide/WritingUNO/Intercepting Context Menus

2008-02-20T20:49:15Z

Holgerbrandl: fixed bugs in example source code

{{Documentation/DevGuide/WritingUNOTOC
|WritingUNO2e=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/WritingUNO/Disable Commands
|NextPage=Documentation/DevGuide/WritingUNO/File Naming Conventions
}}
{{DISPLAYTITLE:Intercepting Context Menus}}
__NOTOC__

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

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

=== Register and Remove an Interceptor ===

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

=== Writing an Interceptor ===

==== Notification ====

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

ContextMenuInterceptorAction notifyContextMenuExecute ( [in] ContextMenuExecuteEvent aEvent)

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

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
!colspan="2"|Members of <idl>com.sun.star.ui.ContextMenuExecuteEvent</idl>
|-
|<idlm>com.sun.star.ui.ContextMenuExecuteEvent:ExecutePosition</idlm>
|<idl>com.sun.star.awt.Point</idl>. Contains the position the context menu will be executed.
|-
|<idlm>com.sun.star.ui.ContextMenuExecuteEvent:SourceWindow</idlm>
|<idl>com.sun.star.awt.XWindow</idl>. Contains the window where the context menu has been requested.
|-
|<idlm>com.sun.star.ui.ContextMenuExecuteEvent:ActionTriggerContainer</idlm>
|<idl>com.sun.star.container.XIndexContainer</idl>. The structure of the intercepted context menu. The member implements the <idl>com.sun.star.ui.ActionTriggerContainer</idl> service.
|-
|<idlm>com.sun.star.ui.ContextMenuExecuteEvent:Selection</idlm>
|<idl>com.sun.star.view.XSelectionSupplier</idl>. Provides the current selection inside the source window.
|}

==== Querying a Menu Structure ====

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

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

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
!Type of Menu Entry
!Service Name
|-
|Menu entry
|"<code>com.sun.star.ui.ActionTrigger</code>"
|-
|Separator
|"<code>com.sun.star.ui.ActionTriggerSeparator</code>"
|}

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

boolean supportsService ( [in] string ServiceName )

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


// A helper class to determine the menu element type
public class MenuElement
{
static public boolean IsMenuEntry( com.sun.star.beans.XPropertySet xMenuElement ) {
com.sun.star.lang.XServiceInfo xServiceInfo =
(com.sun.star.lang.XServiceInfo)UnoRuntime.queryInterface(
com.sun.star.lang.XServiceInfo.class, xMenuElement );

return xServiceInfo.supportsService( "com.sun.star.ui.ActionTrigger" );
}

static public boolean IsMenuSeparator( com.sun.star.beans.XPropertySet xMenuElement ) { com.sun.star.lang.XServiceInfo xServiceInfo =
(com.sun.star.lang.XServiceInfo)UnoRuntime.queryInterface(
com.sun.star.lang.XServiceInfo.class, xMenuElement );

return xServiceInfo.supportsService( "com.sun.star.ui.ActionTriggerSeparator" );
}
}

Figure 4.1: Determine the menu element type

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

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
!colspan="2"|Properties of <idl>com.sun.star.ui.ActionTrigger</idl>
|-
|<idlm>com.sun.star.ui.ActionTrigger:Text</idlm>
|string. Contains the text of the label of the menu entry.
|-
|<idlm>com.sun.star.ui.ActionTrigger:CommandURL</idlm>
|string. Contains the command URL that defines which function will be executed if the menu entry is selected by the user.
|-
|<idlm>com.sun.star.ui.ActionTrigger:HelpURL</idlm>
|string. This optional property contains a help URL that points to the help text.
|-
|<idlm>com.sun.star.ui.ActionTrigger:Image</idlm>
|<idl>com.sun.star.awt.XBitmap</idl>. This property contains an image that is shown left of the menu label. The use is optional so that no image is used if this member is not initialized.
|-
|<idlm>com.sun.star.ui.ActionTrigger:SubContainer</idlm>
|<idl>com.sun.star.container.XIndexContainer</idl>. This property contains an optional sub menu.
|}

The <idl>com.sun.star.ui.ActionTriggerSeparator</idl> service defines only one optional property:

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
!colspan="2"|Property of <idl>com.sun.star.ui.ActionTriggerSeparator</idl>
|-
|<idlm>com.sun.star.ui.ActionTriggerSeparator:SeparatorType</idlm>
|<idl>com.sun.star.ui.ActionTriggerSeparatorType</idl>. Specifies a certain type of a separator. Currently the following types are possible:

* const int LINE = 0
* const int SPACE = 1
* const int LINEBREAK = 2
|}

==== Changing a Menu ====

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

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

The <idl>com.sun.star.lang.XMultiServiceFactory</idl> implementation of the ActionTriggerContainer implementation supports the following strings:

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
!String
!Object
|-
|"com.sun.star.ui.ActionTrigger"
|Creates a normal menu entry.
|-
|"com.sun.star.ui.ActionTriggerContainer"
|Creates an empty sub menu1 .
|-
|"com.sun.star.ui.ActionTriggerSeparator"
|Creates an unspecified separator2 .
|}

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

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

==== Finishing Interception ====

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

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
!colspan="2"|Values of <idl>com.sun.star.ui.ContextMenuInterceptorAction</idl>
|-
|<code>IGNORED</code>
|Called object has ignored the call. The next registered <idl>com.sun.star.ui.XContextMenuInterceptor</idl> should be notified.
|-
|<code>CANCELLED</code>
|The context menu must not be executed. No remaining interceptor will be called.
|-
|<code>EXECUTE_MODIFIED</code>
|The context menu has been modified and should be executed without notifying the next registered <idl>com.sun.star.ui.XContextMenuInterceptor</idl>.
|-
|<code>CONTINUE_MODIFIED</code>
|The context menu was modified by the called object. The next registered <idl>com.sun.star.ui.XContextMenuInterceptor</idl> should be notified.
|}

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


import com.sun.star.ui.*;
import com.sun.star.lang.XMultiServiceFactory;
import com.sun.star.beans.XPropertySet;
import com.sun.star.container.XIndexContainer;
import com.sun.star.uno.UnoRuntime;
import com.sun.star.uno.Exception;
import com.sun.star.beans.UnknownPropertyException;
import com.sun.star.lang.IllegalArgumentException;

public class ContextMenuInterceptor implements XContextMenuInterceptor {

public ContextMenuInterceptorAction notifyContextMenuExecute(
com.sun.star.ui.ContextMenuExecuteEvent aEvent ) throws RuntimeException {

try {

// Retrieve context menu container and query for service factory to
// create sub menus, menu entries and separators
com.sun.star.container.XIndexContainer xContextMenu = aEvent.ActionTriggerContainer;
com.sun.star.lang.XMultiServiceFactory xMenuElementFactory =
(com.sun.star.lang.XMultiServiceFactory)UnoRuntime.queryInterface(
com.sun.star.lang.XMultiServiceFactory.class, xContextMenu );
if ( xMenuElementFactory != null ) {
// create root menu entry for sub menu and sub menu
com.sun.star.beans.XPropertySet xRootMenuEntry =
(XPropertySet)UnoRuntime.queryInterface(
com.sun.star.beans.XPropertySet.class,
xMenuElementFactory.createInstance ( "com.sun.star.ui.ActionTrigger" ));

// create a line separator for our new help sub menu
com.sun.star.beans.XPropertySet xSeparator =
(com.sun.star.beans.XPropertySet)UnoRuntime.queryInterface(
com.sun.star.beans.XPropertySet.class,
xMenuElementFactory.createInstance( "com.sun.star.ui.ActionTriggerSeparator" ) );

Short aSeparatorType = new Short( ActionTriggerSeparatorType.LINE );
xSeparator.setPropertyValue( "SeparatorType", (Object)aSeparatorType );

// query sub menu for index container to get access
com.sun.star.container.XIndexContainer xSubMenuContainer =
(com.sun.star.container.XIndexContainer)UnoRuntime.queryInterface(
com.sun.star.container.XIndexContainer.class,
xMenuElementFactory.createInstance(
"com.sun.star.ui.ActionTriggerContainer" ));

// intialize root menu entry "Help"
xRootMenuEntry.setPropertyValue( "Text", new String( "Help" ));
xRootMenuEntry.setPropertyValue( "CommandURL", new String( "slot:5410" ));
xRootMenuEntry.setPropertyValue( "HelpURL", new String( "5410" ));
xRootMenuEntry.setPropertyValue( "SubContainer", (Object)xSubMenuContainer );

// create menu entries for the new sub menu

// intialize help/content menu entry
// entry "Content"
XPropertySet xMenuEntry = (XPropertySet)UnoRuntime.queryInterface(
XPropertySet.class, xMenuElementFactory.createInstance (
"com.sun.star.ui.ActionTrigger" ));

xMenuEntry.setPropertyValue( "Text", new String( "Content" ));
xMenuEntry.setPropertyValue( "CommandURL", new String( "slot:5401" ));
xMenuEntry.setPropertyValue( "HelpURL", new String( "5401" ));

// insert menu entry to sub menu
xSubMenuContainer.insertByIndex ( 0, (Object)xMenuEntry );

// intialize help/help agent
// entry "Help Agent"
xMenuEntry = (com.sun.star.beans.XPropertySet)UnoRuntime.queryInterface(
com.sun.star.beans.XPropertySet.class,
xMenuElementFactory.createInstance (
"com.sun.star.ui.ActionTrigger" ));
xMenuEntry.setPropertyValue( "Text", new String( "Help Agent" ));
xMenuEntry.setPropertyValue( "CommandURL", new String( "slot:5962" ));
xMenuEntry.setPropertyValue( "HelpURL", new String( "5962" ));

// insert menu entry to sub menu
xSubMenuContainer.insertByIndex( 1, (Object)xMenuEntry );

// intialize help/tips
// entry "Tips"
xMenuEntry = (com.sun.star.beans.XPropertySet)UnoRuntime.queryInterface(
com.sun.star.beans.XPropertySet.class,
xMenuElementFactory.createInstance(
"com.sun.star.ui.ActionTrigger" ));
xMenuEntry.setPropertyValue( "Text", new String( "Tips" ));
xMenuEntry.setPropertyValue( "CommandURL", new String( "slot:5404" ));
xMenuEntry.setPropertyValue( "HelpURL", new String( "5404" ));

// insert menu entry to sub menu
xSubMenuContainer.insertByIndex ( 2, (Object)xMenuEntry );

// add separator into the given context menu
xContextMenu.insertByIndex ( 0, (Object)xSeparator );

// add new sub menu into the given context menu
xContextMenu.insertByIndex ( 0, (Object)xRootMenuEntry );

// The controller should execute the modified context menu and stop notifying other
// interceptors.
return com.sun.star.ui.ContextMenuInterceptorAction.EXECUTE_MODIFIED ;
}
}
catch ( com.sun.star.beans.UnknownPropertyException ex ) {
// do something useful
// we used a unknown property
}
catch ( com.sun.star.lang.IndexOutOfBoundsException ex ) {
// do something useful
// we used an invalid index for accessing a container
}
catch ( com.sun.star.uno.Exception ex ) {
// something strange has happend!
}
catch ( java.lang.Throwable ex ) {
// catch java exceptions - do something useful
}

return com.sun.star.ui.ContextMenuInterceptorAction.IGNORED;
}

{{PDL1}}
[[Category: Writing UNO Components]]

User talk:Holgerbrandl

2007-10-09T22:44:55Z

Holgerbrandl:

[[User:Mmp|Mmp]],10:51, 25 September 2007 (CEST): What is the relation between [[OpenCards]] and the [[MediaWiki Extension]]? You've added it to the MediaWiki category.

[[User:Holgerbrandl|Holgerbrandl]] 00:44, 10 October 2007 (CEST)good point. There's no relation. fixed. :-)

User talk:Holgerbrandl

2007-10-09T22:44:41Z

Holgerbrandl:

[[User:Mmp|Mmp]],10:51, 25 September 2007 (CEST): What is the relation between [[OpenCards]] and the [[MediaWiki Extension]]? You've added it to the MediaWiki category.

--[[User:Holgerbrandl|Holgerbrandl]] 00:44, 10 October 2007 (CEST)good point. There's no relation. fixed. :-)

User talk:Holgerbrandl

2007-10-09T22:44:10Z

Holgerbrandl:

[[User:Mmp|Mmp]],10:51, 25 September 2007 (CEST): What is the relation between [[OpenCards]] and the [[MediaWiki Extension]]? You've added it to the MediaWiki category.

good point. There's no relation. fixed. :-)

OpenCards

2007-10-09T22:42:43Z

Holgerbrandl: /* Team */

[http://www.opencards.info OpenCards] is a flashcard learning extension for OpenOffice Impress. The basic idea of OpenCards is to use slide-titles as flashcard fronts and the slide contents as their backs. Based on state-of-the-art memorization and scheduling algorithms OpenCards will help you to learn any set of flashcards.

== Team ==
# [[User:holgerbrandl|Holger]] (developer)
# Other roles: Doreen (artwork & testing)

== Communication ==
Our major community support and communication tool are the [http://sourceforge.net/forum/?group_id=198974 support forums] hosted at our sourceforge [http://sourceforge.net/projects/opencards/ project page].

[[Category:Extensions]]

OpenCards

2007-10-09T22:42:20Z

Holgerbrandl: removed from unrelated category

[http://www.opencards.info OpenCards] is a flashcard learning extension for OpenOffice Impress. The basic idea of OpenCards is to use slide-titles as flashcard fronts and the slide contents as their backs. Based on state-of-the-art memorization and scheduling algorithms OpenCards will help you to learn any set of flashcards.

== Team ==
# [[User:holgerbrandl|Holger]] (lead and user experience)
# Other roles: Doreen (artwork & testing)

== Communication ==
Our major community support and communication tool are the [http://sourceforge.net/forum/?group_id=198974 support forums] hosted at our sourceforge [http://sourceforge.net/projects/opencards/ project page].

[[Category:Extensions]]

OpenCards

2007-09-21T12:32:27Z

Holgerbrandl: started OpenCards wiki-entry

[http://www.opencards.info OpenCards] is a flashcard learning extension for OpenOffice Impress. The basic idea of OpenCards is to use slide-titles as flashcard fronts and the slide contents as their backs. Based on state-of-the-art memorization and scheduling algorithms OpenCards will help you to learn any set of flashcards.

== Team ==
# [[User:holgerbrandl|Holger]] (lead and user experience)
# Other roles: Doreen (artwork & testing)

== Communication ==
Our major community support and communication tool are the [http://sourceforge.net/forum/?group_id=198974 support forums] hosted at our sourceforge [http://sourceforge.net/projects/opencards/ project page].

[[Category:MediaWiki Extension]]
[[Category:Extensions]]

Extensions repository

2007-08-08T17:11:24Z

Holgerbrandl: /* List of existing Extensions */ Added OpenCards extension

{{Extensions}}

This list provides Extensions that are available for deployment. Some have been tested, some not : Be careful when using them. We can not guarantee them at this level.

If you want to submit some Extensions to be relayed at end-user level through embedded tool, complete this list and send an email on the [mailto:users@extensions.openoffice.org users@extensions.openoffice.org] to inform us that something new is available. Your addon will then be reviewed and you may obtain some feedback on it.

A [[Extensions/website-todo|website is being designed]]. Will be announced when ready - any help appreciated :-)

[[Extensions_repository/Design|Design for Extensions website]]. The design elements which could be used in the extensions website.

For the moment any free licensing is accepted to be listed. [[Extensions_charter|Read the charter]] regarding conditions

If you want to translate an extension, please contact the author. A localization framework will be soon available

== List of existing Extensions ==
* [http://people.redhat.com/caolanm/PhotoAlbum PhotoaAlbumMaker]
:Localized: English - Category: Add-On - License: GPL - OOoVersion: 2.02
:Description: Create digital photo albums with OpenOffice.org Impress

* [http://sourceforge.net/project/showfiles.php?group_id=87718&package_id=200846 BorderLiner]
:Localized: English - Category: Tables - License: LGPL - OOoVersion: 2.02
:Description: An Openoffice.org macro to draw borders in Calc and Writer tables and other objects just with a couple of key strokes

* [http://sourceforge.net/project/showfiles.php?group_id=87718&package_id=105792 History Manager]
:Localized: ?? - Category: ?? - License: ?? - OOoVersion: ??
:Description:

* [http://www.danielnaber.de/languagetool/ LanguageTool]
:Localized: English, German, Polish, Dutch, Latvian - Category: Linguistic - License: LGPL - OOoVersion: 2.x
:Description: Grammar and style checker for English, German, Polish, and Dutch. Initial support for Italian, French, and Spanish. Latvian in preparation.

* [http://www.ooomacros.org/user.php#169339 Multipages]
:Localized: English, German - Category: UI tool - License: LGPL - OOoVersion: 1.1, 2.0, 2.1
:Description: An Openoffice.org macro (extension package) to copy, delete, sort, rename and create multiple document pages automatically

* [http://people.redhat.com/caolanm/oooblogger/ OOOBlogger]
:Localized: English - Category: Writer Tools - License: ?? - OOoVersion: ??
:Description :

* [http://sourceforge.net/projects/ooosvn OOoSVN]
:Localized: English - Category: ?? - License: GPL - OOoVersion: 2.0 or later
:Description: A project to provide change control for OpenOffice.org documents (OpenDocument and *.sx*) via subversion. Transparently checks in internal changes in files and allows users to recover any previous version, view logs and compare with older versions.

* [http://kohei.us/ooo/solver/ Optimization Solver] formerly known as ''LPSolver''
:Localized: English - Category: Calc Tools - License: LGPL - OOoVersion: 2.0
:Description: The Linear and Non-Linear Optimization Solver (or simply the Optimization Solver) is designed to compute an optimized solution that either maximizes or minimizes a given objective of a model while, at the same time, satisfying a set of constraints that may be defined in the model.
:In this wiki: [[Optimization Solver]]

* [http://www.ipd.uka.de/~hauma/svg-import/ SVG Import Filter]
:Localized: ?? - Category: Add-On - License: LGPL - OOoVersion: 2.0
:Description: This Add-On provides a filter to enable the importing of SVG images.

* [http://api.openoffice.org/SDK/snippets/SnippetCreator.zip Code Snippet Creator]
:Localized: ?? - Category: Development tool - License: ?? - OOoVersion: ??
:Description :

* [http://www.openoffice.org/issues/show_bug.cgi?id=26397 Multisave]
:Localized: ?? - Category: ?? - License: ?? - OOoVersion: ??
:Description: A Macro to save a document to multiple format in a few clicks

* [http://en.ooo-info.org/documentation/annotation_tool.html Annotation Tool]
:Localized: ?? - Category: ?? - License: LGPL - OOoVersion: ??
:Description: Extension of the note feature in Writer: text highlighting, quick remove of notes

* [http://www.afk-support.no/pakker/afk-it/OpenOffice2/html/ Mathtype Macros]
:Localized: English - Category: Math tool - License: GPL - OOoVersion: 2.0.x - Platform: Windows
:Description: Macros for insertion of Mathtype objects in OOo Writer on the Windows platform

* [http://quasiwiki.sourceforge.net/ QuasiWiki]
:Localized: English - Category: Wiki - License: GPL - OOoVersion: 2.0.x
:Description: QuasiWiki implements some of the basic principles of wiki in OpenOffice.org Writer. It doesn't turn OpenOffice.org into a fully fledged wiki tool (hence the "quasi" prefix), but rather adds some wiki-like capabilities.

* [http://quasiwiki.sourceforge.net/ txt2tags extension]
:Localized: English - Category: Markup - License: GPL - OOoVersion: 2.0.x
:Description: txt2tags extension allows users to apply [http://txt2tags.sourceforge.net/ txt2tags] markup to the currently opened Writer document.

* [http://sourceforge.net/projects/ooop/ OxygenOffice Professional contents for OpenOffice.org as extension]
:Localized: English, German, Hungarian, French, Italian - Category: Templates, Gallery - License: LGPL - OOoVersion: 2.x
:Description: Extension version of OxygenOffice Professional's extra contents for OpenOffice.org like templates and galleries.
:Download: [http://sourceforge.net/project/showfiles.php?group_id=170021&package_id=208656] Direct link for extension downloads
:Last update: May 10, 2007

* [http://de.openoffice.org/unbranded-source/browse/*checkout*/de/documentation/vorlagen/vorlagen_de_opendoc.oxt German template collection]
:Localized: German - Category: Templates - License: LGPL - OOoVersion: 2.1
:Description: a collection of German templates hosted by the [http://de.openoffice.org Germanophone project]

* [http://ooolilypond.sourceforge.net/ LilyPond for OpenOffice.org]
:Localized: English - Category: Music - License: ? Version: 2.1 [OOoLilyPond is a macro for OpenOffice.org that simplifies the integration of music notation in OpenOffice.org Writer of Impress. It can be used to write a book on music theory or to write down exercises for music instruments or voices which need to be commented with lots of text.]

* [http://www.ooomacros.org/user.php#216044 Pagination]
:Localized: French, English - Category: Writer Add-On - License: LGPL - OOoVersion: 2.x
: Description: A macro to simplify the commands to paginate a document. Brings up a dialog box where you can choose among some options (position, first number, etc.)

* [http://www.ooomacros.org/user.php#217442 Calendrier]
: Localized: French, English - Category: Writer Add-On - License: LGPL - OOoversion: 2.0.4
: Description: A tool to create calendar pages for one month or for one year.

* [http://writerforwriters.blogspot.com/2007/03/email-backup-extension-for.html Email Backup extension]
:Localized: English - Category: Markup - License: GPL - OOoVersion: 2.0.x
:Description: Using the Email Backup extension, you can quickly email a backup copy of the currently opened OpenOffice.org document to a specified email address.

* [http://code.google.com/p/writertools/ Writer's Tools]
:Localized: English - Category: Markup - License: GPL - OOoVersion: 2.0.x
:Description: Writer’s Tools is an OpenOffice.org extension that includes the following macros: Lookup Tool, Google Translate, Email Backup, Multi-format backup, and Open FTP Document.

* [[Extensions_repository/Creative_Commons|Creative Commons extension]]
:Localized: English - Category: Add-on - License: LGPL - OOoVersion: 2.0.x
:Description: Creative Commons extension is an OpenOffice.org extension that allows to insert in a document Creative Commons licensing information.

* [[http://www.pengyou-project.info/en/index.php PengYou]]
:Localized: English, French - Category: Add-on - License: Apache Licence - OOoVersion: 2.x
:Description: The PengYou extension adds a menu to OpenOffice.org that enables you to easily share documents via the PengYou document collaboration server

* [http://gerard.deneux.free.fr/ CADOO.o]
:Localized: French, English - Category: Add-on - License: LGPL - OOoVersion: 2.x
:Description: The CADOO.o extension adds a menu to OpenOffice.org Draw with functions that makes easier to draw technical drawings

* [http://www.opencards.info OpenCards]
:Localized: English (in progess: German, French, Portuguese) - Category: Impress Add-on - License: BSD - OOoVersion: 2.1
:Description: OpenCards is a flashcard learning extension for OpenOffice Impress. The basic idea of OpenCards is to use slide-titles as flashcard fronts and the slide contents as their backs. Based on the Leitner system OpenCards will help you to learn any set of flashcards.

== Others Extensions Lists ==
* [http://linguistico.sf.net/wiki/doku.php?id=ext:estensioni Extensions on linguistico wiki] (in Italian language)

[[Category:Extensions]]

OOoHelpOutline

2007-07-10T03:21:29Z

Holgerbrandl: /* Third Party Sites */

'''Welcome to the outline of existing OpenOffice.org user resources!'''

The OOo Help Outline has recently moved to OpenOffice.org's Wiki to help open its accessibility as much as possible to the OpenOffice.org community, so that all may help to keep it current and reliable.

See also [[Press coverage on OpenOffice.org]] for various articles, reviews and tips related to OpenOffice.org.

==Product==

===Overview===

* [[OOo OnlineHelp]]
* [http://www.openoffice.org/ OpenOffice.org's Home Page]
** [http://www.openoffice.org/product/ OpenOffice.org Product Description]
** [http://www.openoffice.org/sitemap.html OpenOffice.org's Site Map]
** [http://marketing.openoffice.org/2.0/featureguide.html OpenOffice.org 2.0 Office Suite - Guide to New Features]

* [http://documentation.openoffice.org/manuals/index.html OpenOffice.org User Guide]
* [http://support.openoffice.org/index.html OpenOffice.org Support Area]
**List of links to free community support, commercial support and training, OpenOffice.org books, and general community resources.

* [http://openoffice.start4all.com/ openoffice.org.start4all.com]
* [http://en.wikipedia.org/wiki/OpenOffice.org OpenOffice.org at Wikipedia] ([http://en.wikipedia.org/wiki/Category:OpenOffice.org OpenOffice.org Category])
* [http://www.oooforum.org/links.phtml OpenOffice.org Links]

Related Products
* [[StarOffice|StarOffice Office Suite]]
* [http://portableapps.com/apps/office/suites/portable_openoffice Portable OpenOffice.org]

===FAQs===

* [http://user-faq.openoffice.org/ OpenOffice.org User FAQ Project]
* [http://documentation.openoffice.org/faqs/index.html OpenOffice.org Documentation Project FAQs]
* [http://www.openoffice.org/faq.html OpenOffice.org's General FAQs]
* [http://www.bytebot.net/openoffice/faq.html The OpenOffice.org UnOfficial FAQs by Colin Charles]
* [http://oooauthors.org/en/FAQs/ OOoAuthors.org FAQ Compilation]
* [http://www.openoffice.org/FAQs/fontguide.html Font Troubleshooting Guide]

Also from this Wiki:
* [[Font-FAQ]] (in progress)
* [[Bibliographic Hints and Tips]]
* [[VBA|MS Office VBA Macros]]

===Downloads===

* [http://download.openoffice.org/#latest OpenOffice.org Download Central]
* [http://download.openoffice.org/2.0.2/index.html OpenOffice.org 2.0.2]
* [http://download.openoffice.org/1.1.5/index.html OpenOffice.org 1.1.5]
* [http://www.openoffice.org/dev_docs/source/1.0.3/index.html OpenOffice.org 1.0.3.1] (use this for Windows 95)

===Installation===

* [http://documentation.openoffice.org/setup_guide2/index.html OpenOffice.org's Setup Guides for 1.x and 2.x]
** Good stuff: version 2.x of the Setup Guide provides extensive instructions for installation on ''many'' Linux distros and UNIXes (in addition to Windows):
*** Linux: RPM-based distro, Debian-based distro, Gentoo, Slackware
*** UNIX: Solaris, FreeBSD, Mac OS X
** Another install guide for Debian: [http://www.reallylinux.com/docs/oo2install.shtml Installing OpenOffice.org 2.0 for Debian]
** [http://www.oooforum.org/forum/viewtopic.phtml?t=33125 Adding interface language to existing OpenOffice.org]
* [http://www.openoffice.org/dev_docs/instructions.html OOo's Instructions for Installing and Setting Up OpenOffice.org 1.1.x]
* [http://download.openoffice.org/index.html OpenOffice.org's Download Central]
* [http://www.oooforum.org/forum/viewforum.phtml?f=1 OpenOffice.org Forum: Setup and Configuration]
* [http://www.hypermax.net.au/~settantta/ooo/default.html Alex Fisher's OpenOffice.org Introduction]
* [http://www.openoffice.org/FAQs/build_faq.html Build FAQs for OpenOffice.org]

* Dictionaries: Please see [[OOoHelpOutline#Dictionaries|the Dictionaries sub-section]] for further information.
* Java issues
** [http://java.com/java/download/index.jsp Java.sun.com] - Download the [[Wikipedia:JRE|Java Runtime]] for use with OpenOffice.org (required by Base and Wizards)
** See also [[Java and OpenOffice.org]] for more information

* Linux/BSD issues
** [https://wiki.ubuntu.com/SCIM SCIM IME and OpenOffice.org]: Workaround for the gcc ABI incompatibility issue under Linux/BSD.
** [http://www.bluethingy.com/linux/rh8menu.html Editing GNOME2 Menus] for Linux/BSD users

* Mac issues: for Mac users, please see
** [[FAQ Openoffice.org and NeoOffice|FAQ:OpenOffice.org and NeoOffice]] and
** [[MacOS_X|OpenOffice.org for Mac OS X Development pages]]

===OpenOffice.org Applications===

====Calc====

* [http://sc.openoffice.org/ OpenOffice.org's Spreadsheet Project]
* [http://graphics.openoffice.org/chart/chart.html OpenOffice.org Graphics Applications – Charts]
* [http://documentation.openoffice.org/HOW_TO/index.html OpenOffice.org's How-To Documents]
* [http://documentation.openoffice.org/faqs/spreadsheet/index.html Spreadsheet FAQ Index Page]
* [http://sc.openoffice.org/addin_howto.html How to add-in in OpenOffice.org Calc]
* [http://www.oooforum.org/forum/viewforum.php?f=3 OpenOffice.org Forum]
* [http://documentation.openoffice.org/manuals/oooauthors2/0107GS-GettingStartedWithCalc.pdf Getting Started with Calc]
* [http://www.richhillsoftware.com/ OpenOffice Calc Tips]
* [http://www.nostabo.net/openoffice.php OpenOffice.org Calc Tutorials and Resources]
* [http://spreadsheets.about.com/od/openofficecalc/ OpenOffice Calc Tutorials and Tips]
* [http://www.erack.de/bookmarks/D.html#SpreadSheet Links: Develop (targets SpreadSheet section)]
* [http://www.phptr.com/articles/article.asp?p=430837 Make Calc Spreadsheets Dance for You in OpenOffice.org]

====Writer====

* [http://sw.openoffice.org/ OpenOffice.org's Word Processing Project]
* [http://graphics.openoffice.org/chart/chart.html OpenOffice.org Graphics applications – Charts]
* [http://documentation.openoffice.org/HOW_TO/index.html OpenOffice.org's How-To Documents]
* [http://documentation.openoffice.org/faqs/word_processing/index.html Word Processor FAQ Index Page]
* [http://www.oooforum.org/forum/viewforum.php?f=2 OpenOffice.org Forum]
* [http://prdownloads.sourceforge.net/ooodocs/writer_guide_en_1.0.1.zip?download OpenOffice.org Writer Guide] - for OOo 1.0.1
* [http://www.taming-openoffice-org.com/writer/index.htm Taming OpenOffice.org on Writer]
* [http://www.onlineconnections.com.au/public/openoffice/brochureprinting.html Producing a Brochure or Booklet by Kelvin]
* [http://lingucomponent.openoffice.org/download_dictionary.html Spelling, Hyphenation, and Thesaurus Dictionaries: Download / Installation]
* [http://ooovidtutors.sf.net/ Ooovidtutors - OpenOffice.org video tutorials by mimooh]
* [http://www.8daysaweek.co.uk/forums/viewtopic.php?t=34 Page Numbering in OpenOffice.org (a tutorial)]
* ''OOoAuthors:''
** [http://documentation.openoffice.org/manuals/oooauthors2/0106GS-GettingStartedWithWriter.pdf Getting Started with Writer] (free PDF)
** [http://documentation.openoffice.org/manuals/index.html OpenOffice.org 2.0 Writer Guide] (free PDF)
** [http://www.lulu.com/content/180466 Buy a printed copy of the Writer Guide]

====Draw====

* [http://graphics.openoffice.org/ OpenOffice.org Graphics Applications Project]
* [http://documentation.openoffice.org/HOW_TO/index.html OpenOffice.org's How-To Documents]
* [http://documentation.openoffice.org/faqs/drawing_graphics/index.html Drawing FAQ Index Page]
* [http://www.oooforum.org/forum/viewforum.php?f=5 OpenOffice.org Forum]
* ''OOoAuthors:''
** [http://documentation.openoffice.org/manuals/oooauthors2/0108GS-GettingStartedWithDraw.pdf Getting Started with Draw] (free PDF)
** [http://documentation.openoffice.org/manuals/oooauthors2/index.html OpenOffice.org 2.0 Draw Guide] (free PDF)
** [http://www.lulu.com/content/285709 Buy a printed copy of the Draw Guide]
* Two-page PDF sample reference card for
** [http://www.cluesheets.com/SO8DrawCS.pdf StarOffice Draw 8.0]
** [http://www.cuesheets.com/OO2DrawCS.pdf OpenOffice.org Draw 2.0]

====Impress====

* [http://graphics.openoffice.org/ OpenOffice.org Graphics Applications Project]
* [http://documentation.openoffice.org/faqs/presentation/index.html Presentation FAQ Index Page]
* [http://www.oooforum.org/forum/viewforum.phtml?f=4 OpenOffice.org Forum]
* TUX Magazine: [http://www.tuxmagazine.com/node/1000179 Creating a Slide Show from OOo's Built-in Templates]
* James Abela ELT [http://www.jamesabela.co.uk/bus/Impress.html Impress Training]

* ''OOoAuthors:''
** [http://documentation.openoffice.org/manuals/oooauthors2/0109GS-GettingStartedWithImpress.pdf Getting Started with Impress] (free PDF)
** [http://documentation.openoffice.org/manuals/oooauthors2/index.html OpenOffice.org 2.x Impress Guide] (free PDF)
** [http://www.lulu.com/content/881167 Buy a printed copy of the Impress Guide]

====Math / Formula Editor====

* [http://sw.openoffice.org/ OpenOffice.org's Word Processing Project]
* [http://documentation.openoffice.org/HOW_TO/index.html Formula Command Reference and How-to]
* [http://documentation.openoffice.org/faqs/formula/index.html Math FAQ Index Page]
* [http://www.oooforum.org/forum/viewforum.phtml?f=6 OpenOffice.org Forum Math discussion]

''OOoAuthors''
* [http://documentation.openoffice.org/manuals/oooauthors2/0111GS-GettingStartedWithMath.pdf Getting Started with Math] (free PDF)
* [http://documentation.openoffice.org/manuals/oooauthors2/0216WG-MathObjects.pdf Math Objects: The Equation Editor] (free PDF)
*: same as "Getting Started with Math" but also includes reference tables.

''Third-party add-ons for OpenOffice.org Math''
*[http://www.dmaths.org/modules.php?name=Content&pa=showpage&pid=9 Dmaths] (with [http://www.dmaths.com/dmaths/userguide/user_guide_en.html user guide]) - a Math enhancement package for OpenOffice.org licensed under GPL
*[http://ooolatex.sourceforge.net/ OOoLateX] - a set of OpenOffice.org macros designed to integrate LaTeX equations
** Check out the [http://www.oooforum.org/forum/viewtopic.phtml?t=36 LaTeX or OpenOffice.org Math] discussion at OOoForum for more detail.

====HTML====

* [http://sw.openoffice.org/ OpenOffice.org's Word Processing Project]

====Base and Database ====

* [http://en.wikipedia.org/wiki/OpenOffice.org_Base OpenOffice.org Base information and links at Wikipedia]
* [http://dba.openoffice.org/ OpenOffice.org's Database Access Project]
** [http://dba.openoffice.org/howto/index.html OpenOffice.org Database How-Tos]
** [http://dba.openoffice.org/FAQ/index.html OpenOffice.org Database Tips 'n' Tricks]
** [http://documentation.openoffice.org/HOW_TO/index.html Other OpenOffice.org's How-To Documents]

* [http://documentation.openoffice.org/manuals/oooauthors2/0110GS-GettingStartedWithBase.pdf Getting Started with Base]
* [http://sheepdogguides.com/fdb/fdb1main.htm Tutorials on using ooBase] from Sheepdog Guides ''(updated)''
* [http://www.oooforum.org/forum/viewforum.phtml?f=10 OpenOffice.org Forum - Base]

* Macro and Base: [http://www.pitonyak.org/database/ Andrew Pitonyak's OOo Base macro document]
* ODBC and MySQL: [http://www.unixodbc.org/doc/OOoMySQL.pdf OpenOffice.org 1.0, ODBC, and MySQL 'How-tos' by John McCreesh]

* [http://homepage.ntlworld.com/garryknight/linux/oodbase.html Creating Flatfile Databases with OOo and SO 6 by Garry Knight]
* [http://ericzander.com/Publications/OO_MySQL_Tutorial/index.htm OO_MySQL_Tutorial by Eric Zander] (OOo 1.x)
* [http://kienlein.com/pages/oo.html EDV - Systeme Kienlein]
* [http://openoffice.homelinux.org/index.php?module=pagemaster&PAGE_user_op=view_page&PAGE_id=4&MMN_position=5:3 Documenation for Database and JRE]

===Advanced Features and Topics===

====Macros====

* [http://documentation.openoffice.org/HOW_TO/index.html OpenOffice.org's How-To Documents]
* [http://scripting.openoffice.org/ OpenOffice.org's Scripting Home Page]
* [http://www.ooomacros.org/ OOoMacros]
* [http://www.oooforum.org/forum/viewforum.phtml?f=9 Macro and API OpenOffice.org Forum]
* [http://www.oooforum.org/forum/viewforum.phtml?f=11 OpenOffice.org Code Snippets Forum]
* [http://www.pitonyak.org/oo.php Andrew Pitonyak's Macro Information]
* [http://www.darwinwars.com/lunatic/bugs/oo_macros.html Andrew Brown's OpenOffice.org Macro Page]
* [http://homepages.paradise.net.nz/hillview/OOo/ Iannz OpenOffice.org Page]
* [http://www.oooforum.org/forum/viewtopic.phtml?t=4818 How to use OOo with Python on Windows]
* [http://ooodocs.sourceforge.net/modules.php%3fop=modload&name=Downloads&d_op=viewdownload&cid=23 Templates and Macros from OOoDocs.org]
* [http://www.linuxjournal.com/article/7802 OOo Off the Wall: Macros and Add-ons]
* [http://disemia.com/software/openoffice/ dis-Emi-A Software: OpenOffice]
* [http://home.nikocity.de/sysentw/FAQ/SO-FAQ_English_Version/so-faq_english_version.html SO-FAQ]
* [http://perso.wanadoo.fr/moutou/index.html#OOoDoclink UNO/C++ programming (SXW and HTML formats)]

====Styles====

* [http://documentation.openoffice.org/manuals/oooauthors2/0206WG-IntroductionToStyles.pdf Introduction to Styles] (chapter in ''Writer Guide'')
* [http://documentation.openoffice.org/manuals/oooauthors2/0207WG-WorkingWithStyles.pdf Working with Styles] (chapter in ''Writer Guide'')
* [http://www.openoffice.org/servlets/ReadMsg?msgId=685429&listName=users Setting Up to Write Text Vertically]

====Templates====

* [http://documentation.openoffice.org/manuals/oooauthors2/0112GS-WorkingWithTemplates.pdf Working with Templates] (chapter in ''Getting Started with OOo'')

* [http://documentation.openoffice.org/Samples_Templates/User/template/index.html User/Templates]
* [http://ooextras.sourceforge.net/ OOExtras]
* [http://ooodocs.sourceforge.net/modules.php%3fop=modload&name=Downloads&d_op=viewdownload&cid=23 Templates and Macros from OOoDocs.org]

====XML====

* [http://xml.openoffice.org/ OpenOffice.org XML File Format]
* [http://www.w3.org/XML/ Extensible Markup Language (XML)]
* [http://blogs.sun.com/roller/page/shudson310 Scotty's Engineering Log]
* [http://www.oasis-open.org/committees/office/press.php OASIS Open Office XML Format TC]
* [http://books.evc-cit.info/ OpenOffice.org XML Essentials]
* [http://www.zvon.org/ ZVON.org - The Guide to the XML Galaxy]
* [http://www.logilab.org/projects/xmldiff/ Logilab.org - XmlDiff]

==== Format Conversion ====

* For [[Wikipedia:OpenDocument|OpenDocument]] converters, please see the [[Wikipedia:List_of_applications_supporting_OpenDocument#Programmatic_support.2C_filters.2C_converters|List of applications supporting OpenDocument]] at Wikipedia.
* [[Firefox ODFReader extension]], still under heavy development
* [http://xml.openoffice.org/filters.html File Format Filters and Transformation]
* [http://andreas.web-graphics.com/quickguide-sxw-xhtml/ Converting OpenOffice.org documents to XHTML strict with Writer2LaTeX, by Andreas Bovens]
* [http://www.indesko.com/en/downloads/ooo2dbk ooo2dbk]: Generating DocBook XML from OpenOffice.org 1.x documents
** [http://www.tldp.org/LDP/LDP-Author-Guide/html/oo2docbook.html OOo to DocBook guide] from LDP
* [http://nothickmanuals.info/doku.php?id=ooodokuwiki Publishing with OOo Writer and DokuWiki]

====Dictionaries====

* [[Dictionaries]] Spelling, Hyphenation, and Thesaurus Dictionaries: Download / Installation
* [http://oooconv.free.fr/wikipedia/wikipedia_en.html OOoWikipedia]: Connect OpenOffice.org to Wikipedia for dictionary and information lookup
* [http://ooodocs.sourceforge.net/dictinstall/index.html OpenOffice.org Dictionary Installer] (older tool for older versions of OOo)
* [http://ooodi.sourceforge.net/ OOodi - OpenOffice.org Dictionary Installer for Unix]
* [http://lingucomponent.openoffice.org The lingucomponent project]

====Clip Art====

* [http://documentation.openoffice.org/Samples_Templates/User/gallery/index.html Gallery]
* [http://ooextras.sourceforge.net/ OOExtras]
* [http://www.openclipart.org/ Open Clip Art Library]
* [http://srufaculty.sru.edu/david.dailey/public/public_domain.htm Images in the Public Domain]
* [http://earth.prohosting.com/anvils/aboutMe/intro.html OOo Xfig Clipart and Network Icons for OOoDraw by Edward Chan]
* [http://marketing.openoffice.org/art/ OpenOffice.org Art Project]
* [http://www.kfacts.com/oooart/ OOoArt]
* [http://ooo.nicubunu.ro/ Nicu's OpenOffice.org pages]
* [http://hooboo.free.fr/index.php La Mouette et OpenOffice.org]
* [http://ooodocs.sourceforge.net/graphics/ OpenOffice.org Marketing Materials]

===Other Resources and Support Materials===

====General====

* [http://documentation.openoffice.org/ OpenOffice.org's Documentation Project]
* [http://documentation.openoffice.org/manuals/index.html OpenOffice.org User Guide]
* [http://ooodocs.sourceforge.net/ OOoDocs]
* [http://sourceforge.net/project/showfiles.php?group_id=43716 SourceForge.net: Project: OOoDocs: File List]
* [http://documentation.openoffice.org/thirdparty.html OpenOffice.org's Page of Third Party Documentation]
* [http://ooonewsletter.blogspot.com/ The OpenOffice.org Newsletter]
* [http://www.oooforum.org/ OpenOffice.org Forum]
* [http://www.kaaredyret.dk/openoffice.html OpenOffice.org Links by Kaaredyret.dk]
* [http://www.kargs.net/openoffice.html OpenOffice.org Resource Page by Steve Karg]
* [http://www.tutorialsforopenoffice.org/ Tutorials for OpenOffice]
* [http://www.edafe.org/openoffice/index.html edafe.org: openoffice.org (esp. pointed toward win users)]
* [http://www.erack.de/bookmarks/O.html Links: OpenSource - OpenOffice.org]
* [http://www.openoffice-support.net/ Tutorials, Manuals, HowTo's and more] - OOo 1.x
* [http://ooo.chbs.dk/links/ OpenOffice.org Links]
* [http://www.ooo-portal.de/ Das deutsche OpenOffice.org Portal]
* [http://ooo.ximian.com/hackers-guide.html Unofficial OpenOffice Hacker's Guide]
* [http://ooolib.sourceforge.net/ OpenOffice.org Utility Library]
* [http://ooqstart.sourceforge.net/ Open Office QuickStarter applet]
* [http://del.icio.us/tag/openoffice del.icio.us/tag/openoffice]
* [http://why.openoffice.org/ Why OpenOffice.org]
* [http://documentation.openoffice.org/manuals/index.html Getting Started with OpenOffice.org 2.0]

====Books====

* OpenOffice.org 2.x books
** [http://www.amazon.com/OpenOffice-org-2-Guidebook-Solveig-Haugland/dp/0974312029 OpenOffice.org 2 Guidebook]
** [http://www.amazon.com/exec/obidos/ASIN/0672328089 Sams Teach Yourself OpenOffice.org 2, Firefox and Thunderbird for Windows All in One]
** [http://www.lulu.com/content/177729 Getting Started with OpenOffice.org 2.0]
** [http://www.lulu.com/content/690763 OpenOffice.org 2.x Writer Guide]
** [http://www.lulu.com/content/881167 OpenOffice.org 2.x Impress Guide]
** [http://www.lulu.com/content/285709 OpenOffice.org 2.0 Draw Guide]
** [http://www.lulu.com/content/301623 OpenOffice.org 2.0 Migration Guide]
** [http://www.amazon.com/exec/obidos/ASIN/1593270720 Hacking Openoffice.org: Tips, Tricks, and Untold Secrets]
** [http://www.amazon.com/exec/obidos/ASIN/0131879928 Point & Click OpenOffice.org]
** [http://visibooks.com/writer2.html Visibooks Guide to Writer 2.0]
** [http://visibooks.com/calc2.html Visibooks Guide Calc 2.0]
** [http://visibooks.com/impress2.html Visibooks Guide Impress 2.0]
** [http://visibooks.com/base2.html Visibooks Guide Base 2.0]
** [http://www.conciseconceptsinc.com/ A Conceptual Guide to OpenOffice.org 2.0]
** [http://www.cafepress.com/getopenoffice OpenOffice.org and StarOffice Workbooks]
** [http://www.cluesheets.com/ ClueSheets] - Quick Reference Cards for [[StarOffice]] and OpenOffice.org

* OpenOffice.org 1.x books
** [http://www.amazon.com/exec/obidos/ASIN/0131407457 OpenOffice.org 1.0 Resource Kit]
*** [http://www.informit.com/content/downloads/OpenOfficeUpdate.pdf Special Supplement to Changes in OpenOffice.org 1.1] (free PDF download)
** [http://www.amazon.com/exec/obidos/ASIN/0764542222 OpenOffice.org For Dummies]
** [http://www.oreilly.com/catalog/openoffice/ OpenOffice.org Writer: The Free Alternative to Microsoft Word]
** [http://www.hentzenwerke.com/catalog/ooo501.htm OOoSwitch: 501 Things You Wanted to Know About Switching to OpenOffice.org]
** [http://www.samspublishing.com/title/0672326183 Sams Teach Yourself OpenOffice.org All in One]
** [http://www.hentzenwerke.com/catalog/tinyooo.htm The Tiny Guide to OpenOffice.org]
** [http://www.hod-ami.co.il/product.asp?catalog%5Fname=hodami&category%5Fname=Home+and+Office&product%5Fid=59407 עיבוד תמלילים עם OpenOffice 1.x] ([http://www.hod-ami.co.il/images/bookdemo/59407.pdf Sample Chapter])

* [[StarOffice]] books, mostly suitable to OpenOffice.org users
** [http://www.amazon.com/exec/obidos/tg/detail/-/0789728338/ref=pd_sim_books_5/104-9698914-9518356%3fv=glance&s=books Special Edition Using StarOffice 6.0]
** [http://www.amazon.com/exec/obidos/tg/detail/-/0130384739/qid=1038357106/sr=8-4/ref=sr_8_4/103-6157785-3887854%3fv=glance&s=books&n=507846 StarOffice 6.0 Office Suite Companion]

* Linux and OpenOffice.org related books
** [http://www.amazon.com/exec/obidos/ASIN/1886411867 Linux in the Workplace]
** [http://www.amazon.com/gp/product/0131488724 Point & Click Linux]

* XML, OpenOffice.org Macros and Programming
** [http://www.hentzenwerke.com/catalog/oome.htm OpenOffice.org Macros Explained]
** [http://books.evc-cit.info/ OASIS OpenDocument Essentials]

====E Learning====

* [http://training.bytebot.net/ ByteBot.net Training Materials]
* [http://www.desktoplinux.com/news/NS2978835938.html Free online OpenOffice.org support program]
* [http://www.itrainonline.org/itrainonline/mmtk/opensource.shtml ItrainOnline: Resources for Trainers: MMTK: Open Source Software]

====Compatible Applications====

* [http://www.zope.org/Products/CMF/ Content Management Framework (CMF)]
* [http://peccatte.karefil.com/software/Catalogue/CatalogueENG.htm Files Metadata Miner Software]
* [http://gramps.sourceforge.net/ Gramps]
* [http://www.icoya.com/ icoya]
* [http://www.mozilla.org/ Mozilla]
* [http://www.planamesa.com/neojava/en/index.php NeoOffice/J]
* [http://www.opengroupware.org/ OpenGroupware.org]
* [http://plone.org/ Plone]
* [http://www.bezirksreiter.de/PyOpenOffice.htm PyOpenOffice]
* [http://www.scholarsaid.com/ Scholar's Aid]
* [http://www.hj-gym.dk/~hj/writer2latex/ Writer2LaTeX]
* [http://www.logilab.org/projects/xmldiff/ XmlDiff]
* [http://zope.org/ Zope]

==Web Site==

===Search===

* [http://www.openoffice.org/ Search Bar in Upper Right Corner]
* [http://support.openoffice.org/search.html OOo Site Search using Google]
* [http://www.openoffice.org/project/www/issues/query.cgi Issue Tracker Query Page]
* [http://darwinwars.com/lunatic/bugs/quickbugs.html Simplified Bug Finder by Andrew Brown]
* [http://www.openoffice.org/mail_list.html Mail List Archives]
* [http://www.openoffice.org/servlets/SearchList?listName=users Search the Users List Archive]
* [http://search.gmane.org/ Gmane Newsgroup Search Page]

===Documentation===

* [http://www.openoffice.org/nonav/servlets/HelpTOC OpenOffice.org's Web Site Help TOC]
* [http://documentation.openoffice.org/ OpenOffice.org's Documentation Project]
* [http://lingucomponent.openoffice.org/download_dictionary.html Spelling, Hyphenation, and Thesaurus Dictionaries: Download / Installation]
* [http://www.openoffice.org/mail_list.html OpenOffice.org's Mail Lists]
* [http://www.openoffice.org/servlets/SummarizeList?listName=users Browse the Users List]
* [http://www.openoffice.org/servlets/SearchList?listName=users Search the Users List Archives]
* [http://development.openoffice.org/index.html OpenOffice.org for Developers]
* [http://api.openoffice.org/docs/DevelopersGuide/DevelopersGuide.htm Developer's Guide]
* [http://udk.openoffice.org/python/python-bridge.html Python-UNO bridge]

===Issue Tracker===

* [http://qa.openoffice.org/issue_handling/project_issues.html OpenOffice.org's Bugs and Issues Info]
* [http://qa.openoffice.org/index.html OpenOffice.org's QA Project]
* [http://www.kegel.com/openoffice/triage.html OpenOffice.org Issues by Dan Kegel]
* [http://www.openoffice.org/project/www/issues/query.cgi Query Page for Existing Issue Reports]
* [http://darwinwars.com/lunatic/bugs/quickbugs.html Simplified Bug Finder by Andrew Brown]
* [http://www.openoffice.org/servlets/SearchList?listName=users Search the Users List Archives]

===Community===

* [http://www.openoffice.org/ OpenOffice.org's Home Page]
* [http://marketing.openoffice.org/index.html OpenOffice.org Marketing Project]
* [http://www.openoffice.org/copyright/copyrightapproved.html A list of folks who have filed OOo copyright assignments]
* [http://www.openoffice.org/welcome/credits.html A list fo folks who have contributed to OOo]
* [http://www.openoffice.org/mail_list.html OpenOffice.org's Mail Lists: Browse, Search or Subscribe]
* [http://www.openoffice.org/project/www/issues/query.cgi Issue Tracker Query Page]
* IRC chat channel at irc.freenode.net#openoffice.org

===Projects===

* [http://projects.openoffice.org/index.html Project Descriptions, Leaders, and Links to Project Pages]

===Native Languages===

* [http://lingucomponent.openoffice.org/download_dictionary.html Spelling, Hyphenation, and Thesaurus Dictionaries: Download / Installation]
* [http://ooodocs.sourceforge.net/dictinstall/index.html OpenOffice.org Dictionary Installer] (older tool for older versions of OOo)
* [http://l10n.openoffice.org/all_supported_languages.html l10n - All Supported Languages]
* [http://l10n.openoffice.org/languages.html Localization Contact Table]
* [http://native-lang.openoffice.org/ Native Language Confederation]

=== Third Party Sites ===

* [http://oooauthors.org/ OOoAuthors] for community contributions   on [http://oooauthors.org/en/authors/userguide2/ User Guide] and [http://oooauthors.org/en/FAQs/faqfolder_view FAQ] authoring
* [http://www.digitaldistribution.com/about/lessons/ OpenOffice.org 2.0 lessons in Flash format]
* [http://business.newsforge.com/article.pl?sid=05/11/09/2044220 OpenOffice.org training videos in Flash]
* [http://plan-b-for-openoffice.org Plan-B for OpenOffice.org - Support for non technical users]
* [http://inpics.net/ In Pictures: Online computer tutorials based on pictures]
** [http://inpics.net/writer2.html Writer 2.0 In Pictures]
** [http://inpics.net/calc2.html Calc 2.0 In Pictures]
** [http://inpics.net/impress2.html Impress 2.0 In Pictures]
** [http://inpics.net/base2.html Base 2.0 In Pictures]
* [http://www.oooforum.org/ OpenOffice.org Forum]
* [http://ooonewsletter.blogspot.com/ OpenOffice.org Newsletter]
* [http://ooextras.sourceforge.net/ OOExtras: Extras for OpenOffice.org]
* [http://www.taming-openoffice-org.com/ Taming OpenOffice.org]
* [http://openoffice.blogs.com/ OpenOffice.org Tips, Tricks and Ideas]
* [http://mindmeld.cybersite.com.au/ OpenOffice.org Knowledgebase]
* [http://www.whatisopenoffice.org/ What is OpenOffice.org?]
* [http://oooconv.free.fr/wikipedia/wikipedia_en.html OOoWikipedia-Plugin]
* [http://www.gnome.org/projects/ooo/ GNOME/OpenOffice.org]
* [http://kde.openoffice.org/ KDE Integration Project]
* [http://www.opencards.info OpenCards] - A free flashcard learning extension for OpenOffice Impress

===Developer support===

* [http://development.openoffice.org/ OpenOffice.org for Developers]
* [http://planet.go-oo.org/ Planet OpenOffice.org - Developer News]
* [http://ext.openoffice.org.nz/doku.php OpenOffice.org Extensions Wiki]
* [http://perso.wanadoo.fr/moutou/index.html#OOoDoclink UNO automation (in C++)]

OpenOffice NetBeans Integration

2007-06-15T16:41:20Z

Holgerbrandl: /* Other IDEs */

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

= Download and Installation =
Download the latest version from within NetBeans by clicking on Tools - Update Center. See that "Netbeans Update Center" is selected in the list of available centers and click Next. You can find the plugin in the Features section as "OpenOffice.org API Plugin". Install it and try it out! The configuration is self explanatory, for detailed information see [[OpenOffice_NetBeans_Integration#Configuration|Configuration]].

= Features =
Overview of the features included in the current plugin.
== Project Types ==
All project types create working code. Once the wizard is finished, a working
compilable project is created. It may not do anything, but it can be used
in OpenOffice.org from the beginning.

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

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

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

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

== File Types ==
*'''xcu file type'''
Create an empty xcu file type. The files are recognized in NetBeans and
syntax highlighting is supported.

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

*'''UNO idl file type'''
You can use a file type wizard to create idl files. In the first step, you must select the name location
and UNO type (e.g. Service or Interface). You can add additional
information in the second step. When an interface is created, the second step asks about
the functions that the interface should contain. A complete working idl file is created.

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

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

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

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

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

= Preview =
No previews available at the moment.

== Requirements ==
The plugin works only in combination with OpenOffice.org and an appropriate OpenOffice.org Software Development Kit (SDK).

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

For the Add-on wizard you must have the latest version of the uno-skeletonmaker (comes with OpenOffice.org SDK 2.2.0) and you can download a pre-compiled binary from the file section of the [http://api.openoffice.org API] project ([http://api.openoffice.org/files/documents/22/3823/uno-skeletonmaker_linux_x86zip.zip Linux-x86], [http://api.openoffice.org/files/documents/22/3824/uno-skeletonmaker_solaris_sparc.zip Solaris-Sparc], [http://api.openoffice.org/files/documents/22/3825/uno-skeletonmaker_solaris_x86.zip Solaris-x86], [http://api.openoffice.org/files/documents/22/3826/uno-skeletonmaker_windows.zip Windows])

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

The current version of the plugin asks during the installation for an OpenOffice.org and OpenOffice.org SDK installation. You also configure or change both programs later. Note: If you change the OpenOffice.org or OpenOffice.org SDK installation, these changes are effective for newly created projects only. This will be changed in the future, and you will be asked if you want accept these changes for existing projects.

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

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

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

== Known Problems and Missing Features ==

* Context sensitive help does not work on Linux (Solaris not yet tested), even the javadoc generated Java UNO runtime reference documentation does not work on Linux. Under Windows both work as expected.
* The integrated update center module does not work on Unix systems (known bug [http://www.netbeans.org/issues/show_bug.cgi?id=72960&x=23&y=7 72960] in NetBeans which is fixed in NetBeans 6.0). Workaround is to install NetBeans locally where you have write access.
* The backward compatibility mode for Calc Add-Ins creates still an '''.oxt''' extension package. This of course makes no sense for older OpenOffice.org versions because this file extension was first introduced in OO.org 2.0.4. Please simply rename it to '''.uno.pkg'''
* Projects are currently not platform independent. If you want to build a project on a different platform you must adapt the '''<projectname>/nbproject/project-uno.properties''' file by hand.

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

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

== Common Features ==
*'''UNOIDL Support''' Means support of a new file type for UNOIDL files, including compiling, UNOIDL editor with syntax highlighting. A wizard for defining new UNOIDL types should be supported as well.
*'''Debug Support''' Means debug support directly from NetBeans for new built and deployed extensions in the OpenOffice.org process as well as the debugging of scripts in OpenOffice.org.
*'''Support of OpenOffice.org extension package''' This must be defined in detail but it should at least support the browsing of an '' '''.oxt''' '' file in the NetBeans file system similar to jar|zip files.
*'''File type for xcu files''' This must be defined in detail but we can think of a special editor for OpenOffice .org configuration files.

= Quality Assurance =

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

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

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

= Other IDEs =
Although there is no dedicated OpenOffice API plugin for Intellij IDEA, it is still possible to use it for plugin-development. Three steps are necessary:

(0. create a new java-extension using plugin-wizard of the Nebeans plugin.=

1. Add the build.xml generated by Netbeans as an ant-file in IDEA.

2. Add the following jar-libraries to your IDEA-project
* C:/Program Files/OpenOffice.org 2.2/program/classes/juh.jar
* C:/Program Files/OpenOffice.org 2.2/program/classes/jurt.jar
* C:/Program Files/OpenOffice.org 2.2/program/classes/jut.jar
* C:/Program Files/OpenOffice.org 2.2/program/classes/officebean.jar
* C:/Program Files/OpenOffice.org 2.2/program/classes/ridl.jar
* C:/Program Files/OpenOffice.org 2.2/program/classes/unoil.jar

3. Finally, to make the ant-file work in IDEA, it is necessary to define two additional ant-properties (oo.sdk.home, office.home). Afterwards you'll able to build and to deploy your OpenOffice-extensions using IDEA.

= Feedback =
This is a preview only. Everything is under development and needs to be improved. Feedback is welcome and highly appreciated and we would like to invite you to discuss it on [mailto:dev@api.openoffice.org dev@api.openoffice.org] (Note: you have to be subscribed on the mailing list).

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

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

OpenOffice NetBeans Integration

2007-06-15T16:05:30Z

Holgerbrandl: /* Other IDEs */

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

= Download and Installation =
Download the latest version from within NetBeans by clicking on Tools - Update Center. See that "Netbeans Update Center" is selected in the list of available centers and click Next. You can find the plugin in the Features section as "OpenOffice.org API Plugin". Install it and try it out! The configuration is self explanatory, for detailed information see [[OpenOffice_NetBeans_Integration#Configuration|Configuration]].

= Features =
Overview of the features included in the current plugin.
== Project Types ==
All project types create working code. Once the wizard is finished, a working
compilable project is created. It may not do anything, but it can be used
in OpenOffice.org from the beginning.

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

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

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

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

== File Types ==
*'''xcu file type'''
Create an empty xcu file type. The files are recognized in NetBeans and
syntax highlighting is supported.

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

*'''UNO idl file type'''
You can use a file type wizard to create idl files. In the first step, you must select the name location
and UNO type (e.g. Service or Interface). You can add additional
information in the second step. When an interface is created, the second step asks about
the functions that the interface should contain. A complete working idl file is created.

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

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

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

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

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

= Preview =
No previews available at the moment.

== Requirements ==
The plugin works only in combination with OpenOffice.org and an appropriate OpenOffice.org Software Development Kit (SDK).

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

For the Add-on wizard you must have the latest version of the uno-skeletonmaker (comes with OpenOffice.org SDK 2.2.0) and you can download a pre-compiled binary from the file section of the [http://api.openoffice.org API] project ([http://api.openoffice.org/files/documents/22/3823/uno-skeletonmaker_linux_x86zip.zip Linux-x86], [http://api.openoffice.org/files/documents/22/3824/uno-skeletonmaker_solaris_sparc.zip Solaris-Sparc], [http://api.openoffice.org/files/documents/22/3825/uno-skeletonmaker_solaris_x86.zip Solaris-x86], [http://api.openoffice.org/files/documents/22/3826/uno-skeletonmaker_windows.zip Windows])

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

The current version of the plugin asks during the installation for an OpenOffice.org and OpenOffice.org SDK installation. You also configure or change both programs later. Note: If you change the OpenOffice.org or OpenOffice.org SDK installation, these changes are effective for newly created projects only. This will be changed in the future, and you will be asked if you want accept these changes for existing projects.

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

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

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

== Known Problems and Missing Features ==

* Context sensitive help does not work on Linux (Solaris not yet tested), even the javadoc generated Java UNO runtime reference documentation does not work on Linux. Under Windows both work as expected.
* The integrated update center module does not work on Unix systems (known bug [http://www.netbeans.org/issues/show_bug.cgi?id=72960&x=23&y=7 72960] in NetBeans which is fixed in NetBeans 6.0). Workaround is to install NetBeans locally where you have write access.
* The backward compatibility mode for Calc Add-Ins creates still an '''.oxt''' extension package. This of course makes no sense for older OpenOffice.org versions because this file extension was first introduced in OO.org 2.0.4. Please simply rename it to '''.uno.pkg'''
* Projects are currently not platform independent. If you want to build a project on a different platform you must adapt the '''<projectname>/nbproject/project-uno.properties''' file by hand.

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

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

== Common Features ==
*'''UNOIDL Support''' Means support of a new file type for UNOIDL files, including compiling, UNOIDL editor with syntax highlighting. A wizard for defining new UNOIDL types should be supported as well.
*'''Debug Support''' Means debug support directly from NetBeans for new built and deployed extensions in the OpenOffice.org process as well as the debugging of scripts in OpenOffice.org.
*'''Support of OpenOffice.org extension package''' This must be defined in detail but it should at least support the browsing of an '' '''.oxt''' '' file in the NetBeans file system similar to jar|zip files.
*'''File type for xcu files''' This must be defined in detail but we can think of a special editor for OpenOffice .org configuration files.

= Quality Assurance =

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

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

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

= Other IDEs =
Although there is no dedicated OpenOffice API plugin for Intellij IDEA, it is still possible to use it for plugin-development. In order to do so, it's just necessary to add the build.xml generated by using the Netbeans plugin-wizard as ant-file in IDEA.

To make the ant-file work in IDEA, it is necessary to define two additional ant-properties (oo.sdk.home, office.home). Afterwards you'll able to build and to deploy your OpenOffice-extensions using Idea.

= Feedback =
This is a preview only. Everything is under development and needs to be improved. Feedback is welcome and highly appreciated and we would like to invite you to discuss it on [mailto:dev@api.openoffice.org dev@api.openoffice.org] (Note: you have to be subscribed on the mailing list).

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

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

OpenOffice NetBeans Integration

2007-06-15T16:04:43Z

Holgerbrandl: added development instructions for Intellij Idea

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

= Download and Installation =
Download the latest version from within NetBeans by clicking on Tools - Update Center. See that "Netbeans Update Center" is selected in the list of available centers and click Next. You can find the plugin in the Features section as "OpenOffice.org API Plugin". Install it and try it out! The configuration is self explanatory, for detailed information see [[OpenOffice_NetBeans_Integration#Configuration|Configuration]].

= Features =
Overview of the features included in the current plugin.
== Project Types ==
All project types create working code. Once the wizard is finished, a working
compilable project is created. It may not do anything, but it can be used
in OpenOffice.org from the beginning.

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

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

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

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

== File Types ==
*'''xcu file type'''
Create an empty xcu file type. The files are recognized in NetBeans and
syntax highlighting is supported.

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

*'''UNO idl file type'''
You can use a file type wizard to create idl files. In the first step, you must select the name location
and UNO type (e.g. Service or Interface). You can add additional
information in the second step. When an interface is created, the second step asks about
the functions that the interface should contain. A complete working idl file is created.

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

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

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

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

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

= Preview =
No previews available at the moment.

== Requirements ==
The plugin works only in combination with OpenOffice.org and an appropriate OpenOffice.org Software Development Kit (SDK).

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

For the Add-on wizard you must have the latest version of the uno-skeletonmaker (comes with OpenOffice.org SDK 2.2.0) and you can download a pre-compiled binary from the file section of the [http://api.openoffice.org API] project ([http://api.openoffice.org/files/documents/22/3823/uno-skeletonmaker_linux_x86zip.zip Linux-x86], [http://api.openoffice.org/files/documents/22/3824/uno-skeletonmaker_solaris_sparc.zip Solaris-Sparc], [http://api.openoffice.org/files/documents/22/3825/uno-skeletonmaker_solaris_x86.zip Solaris-x86], [http://api.openoffice.org/files/documents/22/3826/uno-skeletonmaker_windows.zip Windows])

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

The current version of the plugin asks during the installation for an OpenOffice.org and OpenOffice.org SDK installation. You also configure or change both programs later. Note: If you change the OpenOffice.org or OpenOffice.org SDK installation, these changes are effective for newly created projects only. This will be changed in the future, and you will be asked if you want accept these changes for existing projects.

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

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

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

== Known Problems and Missing Features ==

* Context sensitive help does not work on Linux (Solaris not yet tested), even the javadoc generated Java UNO runtime reference documentation does not work on Linux. Under Windows both work as expected.
* The integrated update center module does not work on Unix systems (known bug [http://www.netbeans.org/issues/show_bug.cgi?id=72960&x=23&y=7 72960] in NetBeans which is fixed in NetBeans 6.0). Workaround is to install NetBeans locally where you have write access.
* The backward compatibility mode for Calc Add-Ins creates still an '''.oxt''' extension package. This of course makes no sense for older OpenOffice.org versions because this file extension was first introduced in OO.org 2.0.4. Please simply rename it to '''.uno.pkg'''
* Projects are currently not platform independent. If you want to build a project on a different platform you must adapt the '''<projectname>/nbproject/project-uno.properties''' file by hand.

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

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

== Common Features ==
*'''UNOIDL Support''' Means support of a new file type for UNOIDL files, including compiling, UNOIDL editor with syntax highlighting. A wizard for defining new UNOIDL types should be supported as well.
*'''Debug Support''' Means debug support directly from NetBeans for new built and deployed extensions in the OpenOffice.org process as well as the debugging of scripts in OpenOffice.org.
*'''Support of OpenOffice.org extension package''' This must be defined in detail but it should at least support the browsing of an '' '''.oxt''' '' file in the NetBeans file system similar to jar|zip files.
*'''File type for xcu files''' This must be defined in detail but we can think of a special editor for OpenOffice .org configuration files.

= Quality Assurance =

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

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

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

= Other IDEs =
Although there is no dedicated OpenOffice API plugin for Intellij IDEA, it is still possible to use it for plugin-development. In order to do so, it's just necessary to add the build.xml generated by using the Netbeans plugin-wizard as ant-file within Idea.

To make the ant-file work within IDEA, it is necessary to define two additional ant-properties (oo.sdk.home, office.home). Afterwards you'll able to build and to deploy your OpenOffice-extensions using Idea.

= Feedback =
This is a preview only. Everything is under development and needs to be improved. Feedback is welcome and highly appreciated and we would like to invite you to discuss it on [mailto:dev@api.openoffice.org dev@api.openoffice.org] (Note: you have to be subscribed on the mailing list).

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

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