Menus
As explained in the previous section, Apache OpenOffice supports two menu locations where an add-on can be integrated: a top-level menu or the Tools - Add-Ons submenu. The configuration branch org.openoffice.Office.Addons provides two different nodes for these locations:
| Supported sets of org.openoffice.Office.Addons to define an Add-On menu | |
|---|---|
OfficeMenuBar
|
A menu defined in this set will be a top-level menu in the Apache OpenOffice Menu Bar. |
AddonMenu
|
A menu defined in this set will be a pop-up menu which is part of the Add-Ons menu item located on the bottom position of the Tools menu. |
To integrate add-on menu items into the Tools – Add-Ons menu, use the AddonMenu set. The AddonMenu set consists of nodes of type MenuItem. The MenuItem node-type is also used for the submenus of a top-level add-on menu.
| Properties of template MenuItem | |||
|---|---|---|---|
oor:name
|
string. The name of the configuration node. The name must begin with an ASCII letter character. It must be unique within the OfficeMenuBar set. Therefore, it is mandatory to use a schema such as org.openoffice.<developer>.<product>.<addon name> or com.<company>.<product>.<addon name> to avoid name conflicts. Keep in mind that your configuration file will be merged into the Apache OpenOffice configuration branch. You do not know which add-ons, or how many add-ons, are currently installed.The node name of menu items of a submenu must be unique only within their submenu. A configuration set cannot guarantee the order of its entries, so you should use a schema such as string + number, for example “m1”, as the name is used to sort the entries.
| ||
URL
|
string. Specifies the command URL that should be dispatched when the user activates the menu entry. It will be ignored if the MenuItem is the title of a a submenu.
To define a separator you can use the special command URL "private:separator". A separator ignores all other properties. | ||
Title
|
string. Contains the title of a top-level menu item. This property supports localization: The default string, which is used when Apache OpenOffice cannot find a string definition for its current language, uses the value element without an attribute. You define a string for a certain language with the xml:lang attribute. Assign the language/locale to the attribute, for example <value xml:lang="en-US">string</value>.
| ||
ImageIdentifier
|
string. Defines an optional image URL that could address an internal Apache OpenOffice image or an external user-defined image. The syntax of an internal image URL is: private:image/<number> where number specifies the image. External user-defined images are supported using the placeholder variable %origin% representing the folder where the component will be installed. The term %origin% will be exchanged with another placeholder, which is substituted during runtime by Apache OpenOffice to the real installation folder. Since Apache OpenOffice supports two different configuration folders ( user and share ) this mechanism is necessary to determine the installation folder of a component. For example the URL %origin%/image will be substituted to something like vnd.sun.star.expand:$UNO_USER_PACKAGES_CACHE/uno_packages/component.zip.1051610942/image . The placeholder vnd.sun.star.expand:$UNO_USER_PACKAGES_CACHE will then be substituted during runtime by the real path. As the Apache OpenOffice supports bitmaps with 1, 4, 8, 16, 24 bit color depth. Magenta (color value red=0xffff, green=0x0000, blue=0xffff) is used as the transparent color, which means that the background color of the display is used instead of the image pixel color when the image is drawn. For optimal results the size of small images should be 16x16 pixel and for big images 26x26 pixel. Other image sizes are scaled automatically by Apache OpenOffice.If no high contrast image is provided, Apache OpenOffice uses the normal image for high contrast environments. Images that are not valid will be ignored. This property has a higher priority than the | ||
Target
|
string. Specifies the target frame for the command URL. Normally an add-on will use one of the predefined target names:
_top
_parent
_self
_blank
| ||
Context
|
string. A list of service names, separated by a comma, that specifies in which context the add-on menu function should be visible. An empty Context means that the function should visible in all contexts. The Apache OpenOffice application modules use the following services names:
The context service name for add-ons is determined by the service name of the model that is bound to the frame, which is associated with UI element (toolbar, menu bar, …). Thus the service name of the Writer model is | ||
Submenu
|
A set of MenuItem entries. Optional to define a submenu for the menu entry. | ||
The next examples shows a configuration file specifying a single menu item titled Add-On Function 1. The unique node name of the add-on is called org.openoffice.example.addon.example.function1.
<?xml version='1.0' encoding='UTF-8'?>
<oor:component-data xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" oor:name="Addons" oor:package="org.openoffice.Office">
<node oor:name="AddonUI">
<node oor:name="AddonMenu">
<node oor:name="org.openoffice.Office.addon.example.function1" oor:op="replace">
<prop oor:name="URL" oor:type="xs:string">
<value>org.openoffice.Office.addon.example:Function1</value>
</prop>
<prop oor:name="ImageIdentifier" oor:type="xs:string"
<value/>
</prop>
<prop oor:name="Title" oor:type="xs:string">
<value/>
<value xml:lang="en-US">Add-On Function 1</value>
</prop>
<prop oor:name="Target" oor:type="xs:string">
<value>_self</value>
</prop>
<prop oor:name="Context" oor:type="xs:string">
<value>com.sun.star.text.TextDocument</value>
</prop>
</node>
</node>
</node>
Top-level Menu
If you want to integrate an add-on into the Apache OpenOffice Menu Bar, you have to use the OfficeMenuBar set. An OfficeMenuBar set consists of nodes of type PopupMenu.
| Properties of template PopupMenu | |
|---|---|
oor:name
|
string. The name of the configuration node. The name must begin with an ASCII letter character. It must be unique within the OfficeMenuBar set. Therefore, it is mandatory to use a schema such as org.openoffice.<developer>.<product>.<addon name> or com.<company>.<product>.<addon name> to avoid name conflicts. Please keep in mind that your configuration file will be merged into the Apache OpenOffice configuration branch. You do not know what add-ons, or how many add-ons, are currently installed.
|
Title
|
string. Contains the title of a top-level menu item. This property supports localization: The default string, which is used when Apache OpenOffice cannot find a string definition for its current language, uses the value element without an attribute. You define a string for a certain language with the xml:lang attribute. Assign the language/locale to the attribute, for example <value xml:lang="en-US">string</value>.
|
Context
|
string. A list of service names, separated by a comma, that specifies in which context the add-on menu should be visible. An empty context means that the function should be visible in all contexts. The Apache OpenOffice application modules use the following services names:
The context service name for add-ons is determined by the service name of the model that is bound to the frame, which is associated with UI element (toolbar, menu bar, …). Thus the service name of the Writer model is |
Submenu
|
A set of MenuItem entries. Defines the submenu of the top-level menu. It must be defined on a top-level menu otherwise the whole menu will be ignored.For more information how to define a submenu please refer to section Guidelines where the MenuItem template is described.
|
The following example defines a top-level menu titled Add-On example with a single menu item titled Add-On Function 1. The menu item has a self-defined image used for displaying it next to the menu title.In the example the nodes are called oor:name="org.openoffice.example.addon" and oor:name="m1".
Do not forget to specify the oor:op="replace" attribute in your self-defined nodes. The replace operation must be used to add a new node to a set or extensible node. Thus the real meaning of the operation is "add or replace". Dynamic properties can only be added once and are then considered mandatory, so during layer merging the replace operation always means "add" for them.For more details about the configuration and their file formats please read Configuration Management.
<?xml version='1.0' encoding='UTF-8'?>
<oor:component-data xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" oor:name="Addons" oor:package="org.openoffice.Office">
<node oor:name="AddonUI">
<node oor:name="OfficeMenuBar">
<node oor:name="org.openoffice.example.addon" oor:op="replace">
<prop oor:name="Title" oor:type="xs:string">
<value/>
<value xml:lang="en-US">Add-On example</value>
<value xml:lang=”de”>Add-On Beispiel</value>
</prop>
<prop oor:name="Context" oor:type="xs:string">
<value>com.sun.star.text.TextDocument</value>
</prop>
<node oor:name="Submenu">
<node oor:name="m1" oor:op="replace">
<prop oor:name="URL" oor:type="xs:string">
<value>org.openoffice.Office.addon.example:Function1</value>
</prop>
<prop oor:name="Title" oor:type="xs:string">
<value/>
<value xml:lang=”en-US”>Add-On Function 1</value>
<value xml:lang="de">Add-On Funktion 1</value>
</prop>
<prop oor:name="Target" oor:type="xs:string">
<value>_self</value>
</prop>
</node>
</node>
</node>
</node>
</node>
</oor:component-data>
| Content on this page is licensed under the Public Documentation License (PDL). |
