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

From Apache OpenOffice Wiki
Jump to: navigation, search
m
m (Robot: Changing Category:Writing UNO Components)
Line 111: Line 111:
 
</source>
 
</source>
 
{{PDL1}}
 
{{PDL1}}
[[Category: Writing UNO Components]]
+
 
 +
[[Category:Documentation/Developers Guide/Professional UNO]]

Revision as of 06:41, 4 June 2008



An add-on can also be integrated into the Function Bar of OpenOffice.org. 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 OpenOffice.org to group toolbar items from different add-ons. OpenOffice.org automatically inserts a separator between different add-ons toolbar items.

Documentation caution.png The space of the Function Bar is limited, so only the most used/important functions should be added to the OfficeToolBar set. Otherwise OpenOffice.org 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.
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 OpenOffice.org 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 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 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 by the pkgchk tool. The pkgchk tool exchanges %origin% 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 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 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 are 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 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.chart.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 OpenOffice.org 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></nowiki>
Content on this page is licensed under the Public Documentation License (PDL).
Personal tools