Menus

From Apache OpenOffice Wiki
Jump to: navigation, search



As explained in the previous section, OpenOffice.org 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 OpenOffice.org 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 OpenOffice.org 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 OpenOffice.org 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 OpenOffice.org 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 OpenOffice.org to the real installation folder. Since OpenOffice.org 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 OpenOffice.org supports four different images (small/large image and both as high contrast), a naming schema is used to address them. OpenOffice.org 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.

OpenOffice.org 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 OpenOffice.org.If no high contrast image is provided, OpenOffice.org 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 OpenOffice.org 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 OpenOffice.org 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 OpenOffice.org 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 OpenOffice.org 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 OpenOffice.org 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 OpenOffice.org 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