Difference between revisions of "Documentation/DevGuide/WritingUNO/AddOns/Menus"

From Apache OpenOffice Wiki
Jump to: navigation, search
(Submenu in Tools - Add-Ons: Warning on ImageIdentifier. Reference to pkgchk deleted.)
 
(3 intermediate revisions by 3 users not shown)
Line 9: Line 9:
 
{{Documentation/DevGuideLanguages|Documentation/DevGuide/WritingUNO/AddOns/{{SUBPAGENAME}}}}
 
{{Documentation/DevGuideLanguages|Documentation/DevGuide/WritingUNO/AddOns/{{SUBPAGENAME}}}}
 
{{DISPLAYTITLE:Menus}}
 
{{DISPLAYTITLE:Menus}}
As explained in the previous section, {{PRODUCTNAME}} 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:
+
As explained in the previous section, {{AOo}} 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:
  
 
{|border="1" cellpadding=4 style="border-collapse:collapse;"
 
{|border="1" cellpadding=4 style="border-collapse:collapse;"
Line 16: Line 16:
 
|-
 
|-
 
|<code>OfficeMenuBar</code>  
 
|<code>OfficeMenuBar</code>  
|A menu defined in this set will be a top-level menu in the {{PRODUCTNAME}} Menu Bar.  
+
|A menu defined in this set will be a top-level menu in the {{AOo}} Menu Bar.  
 
|-
 
|-
 
|<code>AddonMenu</code>  
 
|<code>AddonMenu</code>  
Line 31: Line 31:
 
|-
 
|-
 
|<code>oor:name</code>  
 
|<code>oor:name</code>  
|string. The name of the configuration node. The name must begin with an ASCII letter character. It must be unique within the <code>OfficeMenuBar</code> set. Therefore, it is mandatory to use a schema such as <code>org.openoffice.<developer>.<product>.<addon name></code> or <code>com.<company>.<product>.<addon name></code> to avoid name conflicts. Keep in mind that your configuration file will be merged into the {{PRODUCTNAME}} 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.   
+
|string. The name of the configuration node. The name must begin with an ASCII letter character. It must be unique within the <code>OfficeMenuBar</code> set. Therefore, it is mandatory to use a schema such as <code>org.openoffice.<developer>.<product>.<addon name></code> or <code>com.<company>.<product>.<addon name></code> to avoid name conflicts. Keep in mind that your configuration file will be merged into the {{AOo}} 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.   
 
|-
 
|-
 
|<code>URL</code>
 
|<code>URL</code>
Line 39: Line 39:
 
|-
 
|-
 
|<code>Title</code>  
 
|<code>Title</code>  
|string. Contains the title of a top-level menu item. This property supports localization: The default string, which is used when {{PRODUCTNAME}} 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 <code>xml:lang attribute</code>. Assign the language/locale to the attribute, for example <code><nowiki><value xml:lang="en-US">string</value></nowiki></code>.  
+
|string. Contains the title of a top-level menu item. This property supports localization: The default string, which is used when {{AOo}} 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 <code>xml:lang attribute</code>. Assign the language/locale to the attribute, for example <code><nowiki><value xml:lang="en-US">string</value></nowiki></code>.  
 
|-
 
|-
 
|<code>ImageIdentifier</code>  
 
|<code>ImageIdentifier</code>  
|{{Documentation/Caution|Since version 2.0.3 of {{OOo}} ''ImageIdentifier'' property has become obsolete. Images should now be in png format, which supports transparency. Png images can only be declared in an [[Documentation/DevGuide/WritingUNO/AddOns/Images_for_Toolbars_and_Menus|Images configuration branch]].}}
+
|{{Warn|Since version 2.0.3 of OpenOffice.org ''ImageIdentifier'' property has become obsolete. Images should now be in png format, which supports transparency. Png images can only be declared in an [[Documentation/DevGuide/WritingUNO/AddOns/Images_for_Toolbars_and_Menus|Images configuration branch]].}}
  
string. Defines an optional image URL that could address an internal {{PRODUCTNAME}} image or an external user-defined image. The syntax of an internal image URL is: ''private:image/<number>'' where number specifies the image.  
+
string. Defines an optional image URL that could address an internal {{AOo}} 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 {{PRODUCTNAME}} to the real installation folder. Since {{PRODUCTNAME}} supports two different configuration folders ( ''user'' and ''share'' ) this mechanism is necessary to determine the installation folder of a component.  
+
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 {{AOo}} to the real installation folder. Since {{AOo}} 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  
 
For example the URL ''%origin%/image'' will be substituted to something like  
Line 55: Line 55:
 
The placeholder ''vnd.sun.star.expand:$UNO_USER_PACKAGES_CACHE'' will then be substituted during runtime by the real path.
 
The placeholder ''vnd.sun.star.expand:$UNO_USER_PACKAGES_CACHE'' will then be substituted during runtime by the real path.
  
As the <code>ImageIdentifier</code> property can only hold one URL but {{PRODUCTNAME}} supports four different images (small/large image and both as high contrast), a naming schema is used to address them. {{PRODUCTNAME}} adds ''_16.bmp'' and ''_26.bmp'' to the provided URL to address the small and large image. ''_16h.bmp'' and ''_26h.bmp'' is added to address the high contrast images. If the high contrast images are omitted the normal images are used instead.
+
As the <code>ImageIdentifier</code> property can only hold one URL but {{AOo}} supports four different images (small/large image and both as high contrast), a naming schema is used to address them. {{AOo}} adds ''_16.bmp'' and ''_26.bmp'' to the provided URL to address the small and large image. ''_16h.bmp'' and ''_26h.bmp'' is added to address the high contrast images. If the high contrast images are omitted the normal images are used instead.
  
{{PRODUCTNAME}} 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.
+
{{AOo}} 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 {{PRODUCTNAME}}.If no high contrast image is provided, {{PRODUCTNAME}} uses the normal image for high contrast environments. Images that are not valid will be ignored. This property has a higher priority than the <code>Images</code> set when {{PRODUCTNAME}} searches for images.   
+
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 {{AOo}}.If no high contrast image is provided, {{AOo}} uses the normal image for high contrast environments. Images that are not valid will be ignored. This property has a higher priority than the <code>Images</code> set when {{AOo}} searches for images.   
 
|-
 
|-
 
|<code>Target</code>  
 
|<code>Target</code>  
Line 77: Line 77:
 
|-
 
|-
 
|<code>Context</code>  
 
|<code>Context</code>  
|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 {{PRODUCTNAME}} application modules use the following services names:
+
|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 {{AOo}} application modules use the following services names:
  
 
* Writer: com.sun.star.text.TextDocument
 
* Writer: com.sun.star.text.TextDocument
Line 84: Line 84:
 
* Draw: com.sun.star.drawing.DrawingDocument
 
* Draw: com.sun.star.drawing.DrawingDocument
 
* Formula:com.sun.star.formula.FormulaProperties
 
* Formula:com.sun.star.formula.FormulaProperties
* Chart: com.sun.star.chart.ChartDocument
+
* Chart: com.sun.star.chart2.ChartDocument
 
* Bibliography:com.sun.star.frame.Bibliography
 
* Bibliography:com.sun.star.frame.Bibliography
  
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 <code>com.sun.star.text.TextDocument</code>. That means, the context name is bound to the model of an application module. If a developer implements a new desktop component that has a model, it is possible to use its service name as a context for add-on UI items.  
+
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 <code>com.sun.star.text.TextDocument</code>. That means, the context name is bound to the model of an application module. If a developer implements a new desktop component that has a model, it is possible to use its service name as a context for add-on UI items.  
 
|-
 
|-
 
|<code>Submenu</code>  
 
|<code>Submenu</code>  
Line 94: Line 94:
  
 
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''.
 
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''.
<source lang="xml">
+
<syntaxhighlight lang="xml">
 
   <?xml version='1.0' encoding='UTF-8'?>
 
   <?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">
 
   <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">
Line 119: Line 119:
 
           </node>
 
           </node>
 
       </node>
 
       </node>
</source>
+
</syntaxhighlight>
  
 
=== Top-level Menu ===
 
=== Top-level Menu ===
  
If you want to integrate an add-on into the {{PRODUCTNAME}} Menu Bar, you have to use the <code>OfficeMenuBar</code> set. An <code>OfficeMenuBar</code> set consists of nodes of type <code>PopupMenu</code>.  
+
If you want to integrate an add-on into the {{AOo}} Menu Bar, you have to use the <code>OfficeMenuBar</code> set. An <code>OfficeMenuBar</code> set consists of nodes of type <code>PopupMenu</code>.  
  
 
{|border="1" cellpadding=4 style="border-collapse:collapse;"
 
{|border="1" cellpadding=4 style="border-collapse:collapse;"
Line 130: Line 130:
 
|-
 
|-
 
|<code>oor:name</code>  
 
|<code>oor:name</code>  
|string. The name of the configuration node. The name must begin with an ASCII letter character. It must be unique within the <code>OfficeMenuBar</code> set. Therefore, it is mandatory to use a schema such as <code>org.openoffice.<developer>.<product>.<addon name></code> or <code>com.<company>.<product>.<addon name></code> to avoid name conflicts. Please keep in mind that your configuration file will be merged into the {{PRODUCTNAME}} configuration branch. You do not know what add-ons, or how many add-ons, are currently installed.  
+
|string. The name of the configuration node. The name must begin with an ASCII letter character. It must be unique within the <code>OfficeMenuBar</code> set. Therefore, it is mandatory to use a schema such as <code>org.openoffice.<developer>.<product>.<addon name></code> or <code>com.<company>.<product>.<addon name></code> to avoid name conflicts. Please keep in mind that your configuration file will be merged into the {{AOo}} configuration branch. You do not know what add-ons, or how many add-ons, are currently installed.  
 
|-
 
|-
 
|<code>Title</code>  
 
|<code>Title</code>  
|string. Contains the title of a top-level menu item. This property supports localization: The default string, which is used when {{PRODUCTNAME}} 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 <code>xml:lang</code> attribute. Assign the language/locale to the attribute, for example <code><nowiki><value xml:lang="en-US">string</value></nowiki></code>.  
+
|string. Contains the title of a top-level menu item. This property supports localization: The default string, which is used when {{AOo}} 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 <code>xml:lang</code> attribute. Assign the language/locale to the attribute, for example <code><nowiki><value xml:lang="en-US">string</value></nowiki></code>.  
 
|-
 
|-
 
|<code>Context</code>  
 
|<code>Context</code>  
|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 {{PRODUCTNAME}} application modules use the following services names:
+
|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 {{AOo}} application modules use the following services names:
  
 
* Writer: com.sun.star.text.TextDocument
 
* Writer: com.sun.star.text.TextDocument
Line 143: Line 143:
 
* Draw: com.sun.star.drawing.DrawingDocument
 
* Draw: com.sun.star.drawing.DrawingDocument
 
* Formula: com.sun.star.formula.FormulaProperties
 
* Formula: com.sun.star.formula.FormulaProperties
* Chart: com.sun.star.chart.ChartDocument
+
* Chart: com.sun.star.chart2.ChartDocument
 
* Bibliography: com.sun.star.frame.Bibliography
 
* Bibliography: com.sun.star.frame.Bibliography
  
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 <code>com.sun.star.text.TextDocument</code>. That means, the context name is bound to the model of an application module. If a developer implements a new desktop component that has a model it is possible to use its service name as a context for add-on UI items.  
+
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 <code>com.sun.star.text.TextDocument</code>. That means, the context name is bound to the model of an application module. If a developer implements a new desktop component that has a model it is possible to use its service name as a context for add-on UI items.  
 
|-
 
|-
 
|<code>Submenu</code>  
 
|<code>Submenu</code>  
Line 155: Line 155:
  
 
Do not forget to specify the <code>oor:op="replace"</code> 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 [[Documentation/DevGuide/Config/Configuration Management|Configuration Management]].  
 
Do not forget to specify the <code>oor:op="replace"</code> 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 [[Documentation/DevGuide/Config/Configuration Management|Configuration Management]].  
<source lang="xml">
+
<syntaxhighlight lang="xml">
 
   <?xml version='1.0' encoding='UTF-8'?>
 
   <?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">
 
   <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">
Line 188: Line 188:
 
       </node>
 
       </node>
 
   </oor:component-data>
 
   </oor:component-data>
</source>
+
</syntaxhighlight>
 
{{PDL1}}
 
{{PDL1}}
  
 
[[Category:Documentation/Developer's Guide/Writing UNO Components]]
 
[[Category:Documentation/Developer's Guide/Writing UNO Components]]

Latest revision as of 15:08, 24 December 2020



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.

Submenu in Tools - Add-Ons

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
Documentation caution.png Since version 2.0.3 of OpenOffice.org ImageIdentifier property has become obsolete. Images should now be in png format, which supports transparency. Png images can only be declared in an Images configuration branch.

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 ImageIdentifier property can only hold one URL but Apache OpenOffice supports four different images (small/large image and both as high contrast), a naming schema is used to address them. Apache OpenOffice adds _16.bmp and _26.bmp to the provided URL to address the small and large image. _16h.bmp and _26h.bmp is added to address the high contrast images. If the high contrast images are omitted the normal images are used instead.

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 Images set when Apache OpenOffice searches for images.

Target string. Specifies the target frame for the command URL. Normally an add-on will use one of the predefined target names:

_top

Returns the top frame of the called frame, which is the first frame where isTop() returns true when traversing up the hierarchy.

_parent

Returns the next frame above in the frame hierarchy.

_self

Returns the frame itself, same as an empty target frame name. This means you are searching for a frame you already have, but it is legal to do so.

_blank

Creates a new top-level frame whose parent is the desktop frame.
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:
  • Writer: com.sun.star.text.TextDocument
  • Spreadsheet:com.sun.star.sheet.SpreadsheetDocument
  • Presentation:com.sun.star.presentation.PresentationDocument
  • Draw: com.sun.star.drawing.DrawingDocument
  • Formula:com.sun.star.formula.FormulaProperties
  • Chart: com.sun.star.chart2.ChartDocument
  • Bibliography:com.sun.star.frame.Bibliography

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 com.sun.star.text.TextDocument. That means, the context name is bound to the model of an application module. If a developer implements a new desktop component that has a model, it is possible to use its service name as a context for add-on UI items.

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:
  • Writer: com.sun.star.text.TextDocument
  • Spreadsheet: com.sun.star.sheet.SpreadsheetDocument
  • Presentation: com.sun.star.presentation.PresentationDocument
  • Draw: com.sun.star.drawing.DrawingDocument
  • Formula: com.sun.star.formula.FormulaProperties
  • Chart: com.sun.star.chart2.ChartDocument
  • Bibliography: com.sun.star.frame.Bibliography

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 com.sun.star.text.TextDocument. That means, the context name is bound to the model of an application module. If a developer implements a new desktop component that has a model it is possible to use its service name as a context for add-on UI items.

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).
Personal tools
In other languages