Help Integration

From Apache OpenOffice Wiki
Jump to: navigation, search



Tip.png Starting with OpenOffice.org 2.4 extensions can contain help content and extend the Apache OpenOffice's installed help content. Add-on Help Integration is now legacy. See instead chapter Help Content.


Apache OpenOffice supports the integration of add-ons into its Help menu. The add-on help menu items are inserted below the Registration menu item, guarded by separators. This guarantees that users have quick access to the add-on help. The OfficeHelp set uses the same MenuItem node-type as the AddonMenu set, but there are some special treatments of the properties.

Properties of template MenuItem
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 help command URL that should be dispatched when the user activates the menu entry. Separators defined by the special command URL "private:separator" are supported, but should not be used in the help menu, because every add-on should only use one menu item.
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 is 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 by 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 will be 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 is 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 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<code> A set of <code>MenuItem entries. Not used for OfficeHelp MenuItems, any definition inside will be ignored.

The following example shows the single help menu item for the add-on example.

  <?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="OfficeHelp"> 
              <node oor:name="com.sun.star.comp.framework.addon" oor:op="replace"> 
                  <prop oor:name="URL" oor:type="xs:string"
                      <value>org.openoffice.Office.addon.example:Help</value> 
                  </prop> 
                  <prop oor:name="ImageIdentifier" oor:type="xs:string">
                      <value/>
                  </prop> 
                  <prop oor:name="Title" oor:type="xs:string"> 
                      <value xml:lang="de">Über Add-On Beispiel</value> 
                      <value xml:lang="en-US">About Add-On Example</value> 
                  </prop> 
                  <prop oor:name="Target" oor:type="xs:string"> 
                      <value>_self</value>
                  </prop> 
              </node> 
          </node>
      </node>
  </oor:component-data>
Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages