Images for Toolbars and Menus

From Apache OpenOffice Wiki
Jump to: navigation, search



OpenOffice.org supports images in menus and toolboxes. In addition to the property ImageIdentifier, the add-ons configuration branch has a fourth set called Images that let developers define and use their own images. The image data can be integrated into the configuration either as hex encoded binary data or as references to external bitmap files. The Images set binds a command URL to user defined images.

Properties of template Images
oor:name string. The name of the configuration node. It must be unique inside the configuration branch. Therefore it is mandatory to use a schema such as org.openoffice.<developer>.<add-on name> or com.<company>.<product>.<add-on 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 how many or which add-ons were installed before by the user.Please be aware that the name must begin with an ASCII letter character.
URL string. Specifies the command URL that should be bound to the defined images. Apache OpenOffice searches for images with the command URL that a menu item/toolbox item contains.
UserDefinedImages Group of properties. This optional group provides self-defined images data to Apache OpenOffice. There are two different groups of properties to define the image data. One property group provides the image data as ongoing hex values specifying an uncompressed bitmap format stream. The other property group uses URLs to external bitmap files. The names of these properties end with 'URL'.

Since OpenOffice.org version 2.0.3, images should be in png format, which supports transparency.

Legacy bitmap (bmp) format is still supported. Apache OpenOffice supports bitmap streams with 1, 4, 8, 16, 24 bit color depth. Magenta (color value red=0xffff, green=0x0000, blue=0xffff) is used as the transparent color, meaning that the background color of the display will be used instead of the image pixel color when the image is drawn.

For best quality, the size of small images should be 16x16 pixel, and for big images 26x26 pixel. Other image sizes will be scaled automatically by Apache OpenOffice. If no high contrast image data is provided, Apache OpenOffice uses the normal image for high contrast environments. Image data that is not valid will be ignored.

An Images node uses a second node called UserDefinedImages where the user defined images data are stored.

Properties of template UserDefinedImages
ImageSmall HexBinary. Used for normal menu/toolbar items, standard size is 16x16 pixel.
ImageBig HexBinary. Only toolbars can use big images. Standard size is 26x26 pixel. The user can activate large buttons with the Tools – Options – View – Large Buttons checkbox.
ImageSmallHC HexBinary. Used for high contrast environments, which means that the background color of a menu or toolbar is below a certain threshold value for the brightness.
ImageBigHC HexBinary. Only toolbars can use big images. Used for high contrast environments, which means that the background color of a toolbar is below a certain threshold value for the brightness.
ImageSmallURL string. An URL to an external image which is used for menu items and normal toolbar buttons. 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%/images will be substituted with something like

 vnd.sun.star.expand:$UNO_USER_PACKAGES_CACHE/uno_packages/component.zip.1051610942/images 

The placeholder vnd.sun.star.expand:$UNO_USER_PACKAGES_CACHE is then substituted during runtime with the real path.


Note #1: As of Apache OpenOffice 4.1.0, %origin% is substituted with something like

 vnd.sun.star.expand:$UNO_USER_PACKAGES_CACHE/uno_packages/svfj5eg0.tmp_/AddOn.oxt/registry/data/org/openoffice/Office/images

As a consequence, a URL to an image example.png that appears on the filesystem to be in AddOn.oxt/images/example.png must be entered as

 %origin%/../../../../../images/example.png

Note #2: As of Apache OpenOffice 4.1.0, a second substitution mechanism can be used. Use the URL schema vnd.sun.star.extension://extension-id/relative-path-within-extension-package where extension-id is the ID of the extension as defined in the description/identifier tag of the file description.xml. For instance, if the ID of an extension is com.example.myproduct.MyExtension and a folder images is at the root of the OXT package, the URL to enter will be

 vnd.sun.star.extension://com.example.myproduct.MyExtension/images/example.png
ImageBigURL string. An URL to an external image which is used for big toolbar buttons.
ImageSmallHCURL string. An URL to an external image which is used for menu items and normal toolbar button in a high contrast environment.
ImageBigHCURL string. An URL to an external image which is used for big toolbar buttons in a high contrast environment.

The embedded image data have a higher priority when used in conjunction with the URL properties. The embedded and URL properties can be mixed without a problem.

The next example creates two user-defined images for the function org.openoffice.Office.addon.example:Function1. The normal image is defined using the embedded image data property ImageSmall and has a size of 16x16 pixel and a 4-bit color depth. The other one uses the URL property ImageSmallHCURL to reference an external bitmap file for the high contrast image. Referencing an external png image would be same, only the extension changes.

  <?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="Images">
              <node oor:name="com.sun.star.comp.framework.addon.image1" oor:op="replace">
                  <prop oor:name="URL" oor:type="xs:string">
                      <value>org.openoffice.Office.addon.example:Function1</value>
                  </prop>
                  <node oor:name=”UserDefinedImages”>
                      <prop oor:name=”ImageSmall”>
                          <value>424df80000000000000076000000280000001000000010000000010004000000000000000000120b0000120b000000000000000000000000ff0000ffff0000ff0000ffff0000ff000000ff00ff00ffffff00c0c0c0008080800000000000000080000080800000800000808000008000000080008000cccccccccccccccc2c266b181b666c2c5cc66b818b6665c555566b181b66655555566b818b66655555566b181b6665555a8666bbb6668a55a0a866666668a0a5000a8666668a000a6000a86668a000a556000a868a000a55556000a8a000a5555556000a000a55555555600000a55555555556000a55555555555560a55555550000</value>
                      </prop>
                      <prop oor:name=”ImageSmallHCURL”>
                          <value>%origin%/function1.bmp</value>
                      </prop>
                  </node>
              </node>
          </node>
      </node>
  </oor:component-data>
Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages