Framework/Article/Tool Panels

Tool Panels

Starting with OpenOffice.org 3.3, the application framework supports so-called tool panels, grouped into a task pane. From previous OpenOffice.org versions, you already know the task pane from Impress, where there are 5 standard tool panels (called "Master Pages", "Layouts", "Table Design", "Custom Animation", and "Slide Transition"). With OpenOffice.org 3.3, you can write your own extension, which adds one or more tool panel/s to one or more of OpenOffice.org's applications.

UI Elements

Conceptually, a tool panel is an UI element, just like tool bars, menu bars, and status bars (to name the most prominent ones). This implies that a toolpanel is identified by a resource URL, starting with private:resource/, followed by a keyword describing the class of the UI element - toolpanel, in our case.

Everything following the mandatory private:resource/toolpanel/ part of the URL is at your discretion. However, remember that your URL must be globally unique, so you should, for example, use your company's name, or something like this. For instance, an example tool panel provided by OOo itself could have an URL like private:resource/toolpanel/org.openoffice.example/ToolPanel, which makes name collisions with other tool panels quite unlikely.

Window States

To make your new tool panel UI element known to the application framework, you need to add meta data about it to the org.openoffice.Office.UI.<Module>WindowState configuration, where <Module> denotes the short name of the application where your panel should appear. Exemplarily, the following configuration fragment registers an examplarily panel for Writer's task pane:

<?xml version='1.0' encoding='UTF-8'?>
<oor:component-data
    oor:name="WriterWindowState"
    oor:package="org.openoffice.Office.UI"
    xmlns:install="http://openoffice.org/2004/installation"
    xmlns:oor="http://openoffice.org/2001/registry"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <node oor:name="UIElements">
    <node oor:name="States">
      <node oor:name="private:resource/toolpanel/org.openoffice.example/SoylentGreen" oor:op="replace">
        <prop oor:name="UIName" oor:type="xs:string">
          <value xml:lang="en-US">Soylent Green</value>
        </prop>
        <prop oor:name="ImageURL" oor:type="xs:string">
          <value>vnd.sun.star.extension://extension-identifier/green.png</value>
        </prop>
      </node>
    </node>
  </node>
</oor:component-data>

Note that the node describing your UI element is a WindowStateType, as defined by the org.openoffice.Office.UI.WindowState configuration scheme. Most of its properties are not used for tool panels, but one of them is mandatory: UIName defines the name of the tool panel, and must not be empty.

Additionally, ImageURL describes an image to associate with the panel. If you deploy an image with your extension, you can use the extension-UCP, which allows you to refer to a file within your extension package, without knowing the actual location to which the package is deployed later on.

Factories

To allow the application framework to create your tool panel when needed, you need to implement an XUIElementFactory for it, and provide information about this factory in the org.openoffice.Office.UI.Factories configuration.

Configuration

<?xml version='1.0' encoding='UTF-8'?>
<oor:component-data
    oor:name="Factories"
    oor:package="org.openoffice.Office.UI"
    xmlns:oor="http://openoffice.org/2001/registry"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <node oor:name="Registered">
    <node oor:name="UIElementFactories">
      <node oor:name="org.openoffice.example.CustomToolPanel" oor:op="replace">
        <prop oor:name="Type">
          <value>toolpanel</value>
        </prop>
        <prop oor:name="Name">
          <value>org.openoffice.example</value>
        </prop>
        <prop oor:name="Module">
          <value/>
        </prop>
        <prop oor:name="FactoryImplementation">
          <value>org.openoffice.example.colorpanel.ToolPanelFactory</value>
        </prop>
      </node>
    </node>
  </node>
</oor:component-data>

Again, the node name for your factory's configuration data should be unique, so apply some common sense when defining it ("MyFactory" is no good name for sure).

The Type property is mandatory and fixed, and must have the value "toolpanel". The Name property effectively is the pattern which is matched against a actual UI element resource URL: The above configuration registers the factory for all UI elements whose resource URL starts with private:resource/toolpanel/org.openoffice.example.

Module can be used to restrict the factory to UI elements in the given module - if your extension registers one or more panels for multiple applications, leave this property empty.

Finally, the FactoryImplementation property specifies the service or implementation name of your UIElementFactory.

Implementation

Your factory's implementation must be a UNO component as usual, which implements the XUIElementFactory interface. In the createUIElement method, the framework will pass two arguments:

• Frame specifies the frame which the UI element lives in. Thus, it provides you access to the document and its view, so can for instance add listeners which react on document/view states, and update your panel state accordingly.
• ParentWindow specifies the window which you must use as parent for your tool panel main window.

Both arguments are guaranteed to be passed to the factory.