Toolbars

From Apache OpenOffice Wiki
Jump to: navigation, search



Add-on toolbar, before version 2.0.3 of OpenOffice.org

An add-on can also be integrated into the Function Bar of Apache OpenOffice. The org.openoffice.Office.Addons configuration branch has a set called OfficeToolBar where you can add toolbar items for an add-on. The toolbar structure uses an embedded set called ToolbarItems, which is used by Apache OpenOffice to group toolbar items from different add-ons. Apache OpenOffice automatically inserts a separator between different add-ons toolbar items.
The space of the Function Bar is limited, so only the most used/important functions should be added to the OfficeToolBar set. Otherwise Apache OpenOffice will add scroll-up/down buttons at the end of the Function Bar and the user has to scroll the toolbar to have access to all toolbar buttons.

Extension toolbar, since version 2.0.3 of OpenOffice.org

Each extension may have its own toolbar. The toolbar may have a specific title.


Properties of template ToolBarItems
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.

The ToolBarItems set is a container for the ToolBarItem nodes.

Properties of template ToolBarItem
oor:name string. The name of the configuration node. It must be unique inside your own ToolBarItems set. A configuration set cannot guarantee the order of its entries, therefore use a schema such as string + number, for example "m1", as the name is used to sort the entries. Please be aware that the name must begin with an ASCII letter character.
URL string. Specifies the command URL that should be dispatched when the user activates the menu entry. 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 with 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 is then substituted during runtime with the real path.

Since 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 are 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 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 an 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 you implement 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 following example defines one toolbar button for the function called org.openoffice.Office.addon.example:Function1. The toolbar button is only visible when using the Apache OpenOffice Writer module.

  <?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="OfficeToolBar">
              <node oor:name="org.openoffice.Office.addon.example" oor:op="replace">
                  <node oor:name=”m1”>
                      <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”>Function 1</value>
                          <value xml:lang="de">Funktion 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>
      </node>
  </oor:component-data>

Toolbar title

Since version 2.0.3 of OpenOffice.org an extension toolbar may have a specific title.

The framework based layout manager uses a modified resource URL schema to address add-on toolbars:

private:resource/toolbar/addon_<name of the toolbar set node>

As the new schema uses a unique name which is known at installation time, the toolbar name can be associated to this resource URL.

In the above example of Addons.xcu file defining a toolbar, the name of the toolbar set node is org.openoffice.Office.addon.example. Therefore the resource URL will be

private:resource/toolbar/addon_org.openoffice.Office.addon.example

An extension can define the toolbar title with <Module>WindowState.xcu files. The title of the toolbar must be set for each module where the toolbar will appear. One such file is necessary for each module. Continuing the example, the toolbar title for Writer module will be specified in a WriterWindowState.xcu file:

<?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="WriterWindowState" oor:package="org.openoffice.Office.UI">
  <node oor:name="UIElements">
    <node oor:name="States">
      <node oor:name="private:resource/toolbar/addon_org.openoffice.Office.addon.example" oor:op="replace">
        <prop oor:name="UIName" oor:type="xs:string">
          <value xml:lang="en-US">My pretty bar</value>
        </prop>
      </node>
    </node>
  </node>
</oor:component-data>

The UIName property supports localization.

Each <Module>WindowState.xcu file must be declared as a configuration data file in the manifest.xml file.

Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages