Framework/WorkInProgress/Addon Menu Toolbar Merging

New feature for Add-ons to merge into OpenOffice.org menu bar and toolbars

Current state

The current add-on implementation in OpenOffice.org provides the following declarative methods to add commands to the user interface:

• AddonMenu

The commands of an add-on are added as a popup menu to a menu item located below the „Tools“ menu, called „Add-on“. The „Add-on“ menu item is automatically added/removed, if add-on commands are available/not available.

• OfficeMenuBar

The commands of an add-on are added as a separate top-level popup-menu. Every add-on top-level popup menu is added between the „Tools“ and „Window“ popup menu.

• OfficeToolBar

The commands of an add-on are added to a separate add-on toolbar. The user can show/hide and dock/undock this toolbar independently from other toolbars.

• OfficeHelp

A special help menu item is added to the „Help“ popup menu. They are located in their own section between the „Registration...“ and „About OpenOffice/StarOffice“ menu item.

OpenOffice.org does have some ways to integrate add-on commands to the user interface. Although this approach should satisfy most developers, there are some who want to have more freedom where add-on commands should be located. Especially the menu bar is a central user interface element where developers want to have a better control. For example the are some developers who wants to implement alternative save commands, which should be placed in the „File“ menu near the other save methods.

There is an API based solution for developers who wants to integrate their commands to the user interface at defined positions, but it needs some effort to implement it correctly. Another drawback is that every developer has to do this implementation again and again which makes add-on development costly.

Proposed solution

A declarative solution to add commands from add-ons to any position in the menu bar would make development much easier. Therefore the Addon.xcs schema configuration file must be extended to support this requirement. The following chapter describes which elements have to be added to provide a flexible and powerful merge mechanism. The green parts describe the additional definitions.

[xml] <!DOCTYPE oor:component-schema SYSTEM "../../../../component-schema.dtd"> <oor:component-schema xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" oor:name="Addons" oor:package="org.openoffice.Office" xml:lang="en-US">

<info>
 <author>CD</author>
 <desc >Contains general structures used to integrate external components into the Office user interface.</desc>
</info>
<templates>
 <group oor:name="MergeMenuInstruction">
  <info>
   <desc>Describes a merge menu instruction of an external component. The name must be unique and should be written using a package-scheme like org.openoffice.external.applicationexecuter to minimize name clashes. A menu instruction describes how the attached menu items should be merged into the Office menubar.
   </desc>
  </info>
  <prop oor:name="MergePoint" oor:type="xs:string">
   <info>
    <desc>A command URL which represents the function to execute.</desc>
   </info>
  </prop>
  <prop oor:name="MergeCommand" oor:type="xs:string">
   <info>
    <desc>A localized string used to as the menu item title.</desc>
   </info>
  </prop>
  <prop oor:name="MergeFallback" oor:type="xs:string">
   <info>
    <desc>A localized string used to as the menu item title.</desc>
   </info>
  </prop>
  <set oor:name="MenuItems" oor:node-type="MenuItem">
   <info>
    <desc>An optional set to allow sub menus.</desc>
   </info>
  </set>
 </group>
 <group oor:name="MenuItem">
  <info>
   <desc>Describes a menu item representing a function of of an external component. The name must be unique and should be written using a package-scheme like org.openoffice.external.applicationexecuter to minimize name clashes.</desc>
  </info>
  <prop oor:name="URL" oor:type="xs:string">
   <info>
    <desc>A command URL which represents the function to execute.</desc>
   </info>
  </prop>
  <prop oor:name="Title" oor:type="xs:string" oor:localized="true">
   <info>
    <desc>A localized string used to as the menu item title.</desc>
   </info>
  </prop>
  <prop oor:name="ImageIdentifier" oor:type="xs:string">
   <info>
    <desc>A private URL used to reference an optional internal menu image. Example: private:image/3216 addresses the internal Office image with id=3216.</desc>
   </info>
  </prop>
  <prop oor:name="Target" oor:type="xs:string">
   <info>
    <desc>This is the target URL which is used for the dispatch command. There are special URL's to address certain targets: _self, current frame; _default, default; _blank, create new frame.</desc>
   </info>
  </prop>
  <prop oor:name="Context" oor:type="xs:string">
   <info>
    <desc>An property to define the context of a menu item that has a sub menu. It can be empty or a colon separated list of the supported application modules.</desc>
   </info>
  </prop>
  <set oor:name="Submenu" oor:node-type="MenuItem">
   <info>
    <desc>An optional set to allow sub menus.</desc>
   </info>
  </set>
 </group>
 <group oor:name="PopupMenu">
  <info>
   <desc>Describes a menu item/toolbar item representing a function of an external component. The name must be unique and should be written using a package-scheme like org.openoffice.external.applicationexecuter to minimize name clashes.</desc>
  </info>
  <prop oor:name="Title" oor:type="xs:string" oor:localized="true">
   <info>
    <desc>A localized string used to as the menu title.</desc>
   </info>
  </prop>
  <prop oor:name="Context" oor:type="xs:string">
   <info>
    <desc>An property to define the context of a top-level popup-menu . It can be empty or a colon separated list of the supported application modules.</desc>
   </info>
  </prop>
  <set oor:name="Submenu" oor:node-type="MenuItem">
   <info>
    <desc>An optional set to allow sub menus. This property cannot be used for toolbar item definitions.</desc>
   </info>
  </set>
 </group>
 <group oor:name="ToolBarItem">
  <info>
   <desc>Describes a toolbar item representing a function of of an external component. The name must be unique and should be written using a package-scheme like org.openoffice.external.applicationexecuter to minimize name clashes.</desc>
  </info>
  <prop oor:name="URL" oor:type="xs:string">
   <info>
    <desc>A command URL which represents the function to execute.</desc>
   </info>
  </prop>
  <prop oor:name="Title" oor:type="xs:string" oor:localized="true">
   <info>
    <desc>A localized string used to as the menu item title.</desc>
   </info>
  </prop>
  <prop oor:name="ImageIdentifier" oor:type="xs:string">
   <info>
    <desc>A private URL used to reference an optional internal menu image. Example: private:image/3216 addresses the internal Office image with id=3216.</desc>
   </info>
  </prop>
  <prop oor:name="Target" oor:type="xs:string">
   <info>
    <desc>This is the target URL which is used for the dispatch command. There are special URL's to address certain targets: _self, current frame; _default, default; _blank, create new frame.</desc>
   </info>
  </prop>
  <prop oor:name="Context" oor:type="xs:string">
   <info>
    <desc>An property to define the context of a toolbar item. It can be empty or a colon separated list of the supported application modules.</desc>
   </info>
  </prop>
 </group>
 <group oor:name="UserDefinedImages">
  <info>
   <desc>A group of optional user-defined images. There are two ways to define image - 1. Embed the image data directly into the configuration. 2. Use file URLs to address external bitmap files. Embedded image data has a higher priority than file URLs.</desc>
  </info>
  <prop oor:name="ImageSmall" oor:type="xs:hexBinary">
   <info>
    <desc>Binary bitmap data used for menu images and small toolbox buttons. Standard size of a small image is 16x16 pixel.</desc>
   </info>
  </prop>
  <prop oor:name="ImageBig" oor:type="xs:hexBinary">
   <info>
    <desc>Binary bitmap data used for big toolbox buttons. Standard size of a big image is 26x26 pixel.</desc>
   </info>
  </prop>
  <prop oor:name="ImageSmallHC" oor:type="xs:hexBinary">
   <info>
    <desc>Binary bitmap data used for high contrast displays. Standard size of a small image is 16x16 pixel.</desc>
   </info>
  </prop>
  <prop oor:name="ImageBigHC" oor:type="xs:hexBinary">
   <info>
    <desc>Binary bitmap data used for high contrast displays. Standard size of a big image is 26x26 pixel.</desc>
   </info>
  </prop>
  <prop oor:name="ImageSmallURL" oor:type="xs:string">
   <info>
    <desc>A file URL to address a external bitmap file used for menu images and/or small toolbox buttons. Standard size of an small image is 16x16 pixel.</desc>
   </info>
  </prop>
  <prop oor:name="ImageBigURL" oor:type="xs:string">
   <info>
    <desc>A file URL to address a external bitmap file used for big toolbox buttons. Standard size of an big image is 26x26 pixel.</desc>
   </info>
  </prop>
  <prop oor:name="ImageSmallHCURL" oor:type="xs:string">
   <info>
    <desc>A file URL to address a external bitmap file usedxfor high contrast menu images and/or toolbox buttons. Standard size of an small image is 16x16 pixel.</desc>
   </info>
  </prop>
  <prop oor:name="ImageBigHCURL" oor:type="xs:string">
   <info>
    <desc>A file URL to address a external bitmap file used for big high contrast toolbox buttons. Standard size of an big image is 26x26 pixel.</desc>
   </info>
  </prop>
 </group>
 <group oor:name="Images">
  <info>
   <desc>A group that associates images to a command URL</desc>
  </info>
  <prop oor:name="URL" oor:type="xs:string">
   <info>
   <desc>The command URL that is bound to the defined images.</desc>
   </info>
  </prop>
  <node-ref oor:name="UserDefinedImages" oor:node-type="UserDefinedImages">
   <info>
    <desc>An user-defined images group.</desc>
   </info>
  </node-ref>
 </group>
 <set oor:name="ToolBarItems" oor:node-type="ToolBarItem">
  <info>
   <desc>Contains a list of toolbar items used by an Add-On.</desc>
  </info>
 </set>
 <set oor:name="MergeMenuItems" oor:node-type="MergeMenuInstruction">
  <info>
   <desc>Contains a list of merge menu instructions defined by an Add-On which specify how to merge menu items into the Office menubar.</desc>
  </info>
 </set>
</templates>
<component>
 <group oor:name="AddonUI">
  <info>
   <desc>Contains information about the structure of addon user interface.</desc>
  </info>
  <set oor:name="AddonMenu" oor:node-type="MenuItem">
   <info>
    <desc>Contains the structure of the addon menu used by the Office. It provide functions of external components to the user.</desc>
   </info>
  </set>
  <set oor:name="Images" oor:node-type="Images">
   <info>
    <desc>Contains the structure for user-defined images which can be used by menu items and toolbar buttons.</desc>
   </info>
  </set>
  <set oor:name="OfficeMenuBar" oor:node-type="PopupMenu">
   <info>
    <desc>Contains the structure of addon popup-menus inserted into the Office menubar. It provide functions of external components to the user.</desc>
   </info>
  </set>
  <set oor:name="OfficeToolBar" oor:node-type="ToolBarItems">
   <info>
    <desc>Contains a list of sets of toolbar items inserted into the Office function bar.</desc>
   </info>
  </set>
  <set oor:name="OfficeHelp" oor:node-type="MenuItem">
   <info>
    <desc>Contains a list of functions inserted into the Office help menu. The optional property 'Submeno' will be ignored for this set.</desc>
   </info>
  </set>
  <set oor:name="MergeOfficeMenuBar" oor:node-type="MergeMenuItems">
   <info>
    <desc>Contains a list of sets of menu items which should be merged into the Office menubar.</desc>
   </info>
  </set>
 </group>
</component>

</oor:component-schema>